core

README

Core

core is the GraphJin compiler and runtime library.

Module path:

github.com/aegion-dynamic/graphjin-slim/core/v3

It turns GraphQL operations into database queries, executes them, and returns structured results. The package is intended to be embedded by Go applications; it does not start an HTTP server and does not own application authentication or application routing.

Public Entry Points

The stable public surface is in the root core package.

Important types and functions include:

core.NewGraphJin
core.NewGraphJinWithFS
core.GraphJin
core.Config
core.Option
core.Result

The typical flow is:

engine, err := core.NewGraphJin(conf, db)
if err != nil {
	return err
}
defer engine.Close()

result, err := engine.GraphQL(ctx, query, variables, requestConfig)

Use core.NewTestGraphJin from testkit.go for schema-backed tests that do not need a live database.

Responsibilities

Core owns:

• GraphQL parsing and AST validation
• Schema discovery and relationship modeling (sdata)
• Pure query, mutation, and subscription compilation (qcode)
• SQL generation for Postgres and SQLite (psql, dialect)
• Allow-list enforcement for saved queries
• Result encoding and pagination
• Runtime schema discovery and reloads
• Response-cache integration hooks

Core does not own:

• HTTP routing
• Server startup and shutdown
• Application authentication / role evaluation (GraphJin Slim is host-agnostic)
• Application-specific authorization middleware
• Redis connection lifecycle
• CLI commands

Sub-packages

The compiler sub-packages provide modular stages in the compilation pipeline:

Package	Responsibility
core/engine	Core query execution pipeline, prepared statement caching, and gstate lifecycle
core/dbjoin	Cross-database distributed joins and multi-database result merging
core/watcher	Background database schema polling, change callbacks, and shutdown lifecycle
core/runtime	Execution resilience, exponential backoff retry, field crypto, and error repair diagnostics
core/graph	GraphQL lexer, parser, and syntax schema
core/qcode	Normalized GraphQL query compiler and intermediate representation (IR)
core/sqlgen	SQL query and mutation compilation
core/dialect	Postgres and SQLite rendering differences
core/sdata	Database metadata and schema relationships
core/introspection	Database metadata discovery queries
core/jsn	Specialized JSON scanning and mutation helpers
core/allow	Saved-query allow-list storage and matching
core/valid	Shared validation helpers
core/storage	Filesystem and storage abstraction interfaces
core/util	Small compiler data structures and graph utilities
core/schema	GraphQL introspection schema generation

Request Pipeline

GraphQL text
    |
    v
core/graph (lexer & parser)
    |
    v
core/qcode (normalized IR & validation)
    |
    v
core/sdata (schema metadata & relationships)
    |
    v
core/sqlgen + core/dialect (SQL compiler)
    |
    v
SQL and bound arguments
    |
    v
database/sql execution
    |
    v
core.Result (JSON response)

Schema discovery is separate from query compilation conceptually: the compiler consumes schema metadata, while discovery creates and refreshes that metadata.

Database Support

The slim runtime supports:

• Postgres
• SQLite

The dialect and introspection code should preserve that boundary. Removed database implementations and tests should not be reintroduced through generic fallback code.

Testing

Run the core suite from the workspace root:

go test ./core/...
go vet ./core/...

Use the lowest-level package tests for compiler behavior and root-package tests for public runtime behavior. Prefer synthetic schema fixtures and SQLite over requiring an external database.

Refactoring Rules

• Keep core/v3 stable for consumers.
• Keep internal packages below the public root package.
• Put schema discovery behind a schema interface instead of letting query code discover tables directly.
• Keep GraphQL parsing out of runtime execution.
• Move behavior into deep modules with small interfaces rather than creating forwarding packages.

Documentation

Overview

Package core provides an API to include and use the GraphJin compiler with your own code. For detailed documentation visit https://graphjin.com

Index

• Constants
• Variables
• type Cache
• type Column
• type Config
• type DatabaseConfig
• type Engine
• type Error
• type FS
• type Function
• type GraphJin
• type Header
• type Lifecycle
• type Member
• type OpType
• type OpenAPIInputs
• type Option
• type RelationshipConfig
• type RequestConfig
• type Resolver
• type ResolverConfig
• type ResolverFn
• type ResolverProps
• type ResolverReq
• type Result
• type RootLimitInfo
• type RowRef
• type SavedQueryDetails
• type SavedQueryFragment
• type SavedQuerySaveHook
• type SavedQuerySaveRequest
• type SavedQuerySummary
• type SchemaCallbacks
• type Table
• type Tracer

Constants

const (
	DefaultDBName  = engine.DefaultDBName
	OpUnknown      = engine.OpUnknown
	OpQuery        = engine.OpQuery
	OpSubscription = engine.OpSubscription
	OpMutation     = engine.OpMutation
)

Variables

var (
	NewGraphJin                         = engine.NewGraphJin
	NewGraphJinWithFS                   = engine.NewGraphJinWithFS
	NewTestGraphJin                     = engine.NewTestGraphJin
	NewOsFS                             = engine.NewOsFS
	NewLifecycle                        = engine.NewLifecycle
	CanonicalMode                       = engine.CanonicalMode
	OptionSetNamespace                  = engine.OptionSetNamespace
	OptionSetFS                         = engine.OptionSetFS
	OptionSetDatabases                  = engine.OptionSetDatabases
	OptionSetSavedQuerySaveHook         = engine.OptionSetSavedQuerySaveHook
	OptionSetRuntimeSchemaDDLDir        = engine.OptionSetRuntimeSchemaDDLDir
	OptionSetRuntimeSchemaCacheFirst    = engine.OptionSetRuntimeSchemaCacheFirst
	OptionSetRuntimeSchemaCacheRequired = engine.OptionSetRuntimeSchemaCacheRequired
	OptionSetDBSchemaWatcherDisabled    = engine.OptionSetDBSchemaWatcherDisabled
	OptionSetTrace                      = engine.OptionSetTrace
	OptionSetResolver                   = engine.OptionSetResolver
	ErrNotFound                         = engine.ErrNotFound
	RepairKindTableNotFound             = engine.RepairKindTableNotFound
)

Types

type Cache

type Cache = engine.Cache

type Column

type Column = engine.Column

type Config

type Config = engine.Config

type DatabaseConfig

type DatabaseConfig = engine.DatabaseConfig

type Engine

type Engine = engine.Engine

type Error

type Error = engine.Error

type FS

type FS = engine.FS

type Function

type Function = engine.Function

type GraphJin

type GraphJin = engine.GraphJin

type Header

type Header = engine.Header

type Lifecycle

type Lifecycle = engine.Lifecycle

type Member

type Member = engine.Member

type OpType

type OpType = engine.OpType

type OpenAPIInputs

type OpenAPIInputs = engine.OpenAPIInputs

type Option

type Option = engine.Option

type RelationshipConfig

type RelationshipConfig = engine.RelationshipConfig

type RequestConfig

type RequestConfig = engine.RequestConfig

type Resolver

type Resolver = engine.Resolver

type ResolverConfig

type ResolverConfig = engine.ResolverConfig

type ResolverFn

type ResolverFn = engine.ResolverFn

type ResolverProps

type ResolverProps = engine.ResolverProps

type ResolverReq

type ResolverReq = engine.ResolverReq

type Result

type Result = engine.Result

type RootLimitInfo

type RootLimitInfo = engine.RootLimitInfo

type RowRef

type RowRef = engine.RowRef

type SavedQueryDetails

type SavedQueryDetails = engine.SavedQueryDetails

type SavedQueryFragment

type SavedQueryFragment = engine.SavedQueryFragment

type SavedQuerySaveHook

type SavedQuerySaveHook = engine.SavedQuerySaveHook

type SavedQuerySaveRequest

type SavedQuerySaveRequest = engine.SavedQuerySaveRequest

type SavedQuerySummary

type SavedQuerySummary = engine.SavedQuerySummary

type SchemaCallbacks

type SchemaCallbacks = engine.SchemaCallbacks

type Table

type Table = engine.Table

type Tracer

type Tracer = engine.Tracer