shape

repository/shape

repository/shape provides a dynamic, in-memory pipeline for building Datly runtime artifacts from either:

• Go structs (scan -> plan -> load)
• DQL (compile -> load)

without generating YAML route/resource files.

Packages

• shape/scan: discovers view/state tags from struct fields (Embedder-aware).
• shape/plan: normalizes scan output into a deterministic shape plan.
• shape/load: materializes view.Resource, view.View, and a runtime-neutral component artifact.
• shape/compile: compiles DQL into a shape plan for dynamic loading.

Facade API

Use shape.Engine or package helpers:

• shape.LoadViews(ctx, src, opts...)
• shape.LoadComponent(ctx, src, opts...)
• shape.LoadDQLViews(ctx, dql, opts...)
• shape.LoadDQLComponent(ctx, dql, opts...)

Minimal Struct Flow

engine := shape.New(
    shape.WithScanner(scan.New()),
    shape.WithPlanner(plan.New()),
    shape.WithLoader(load.New()),
    shape.WithName("/v1/api/report"),
)

views, err := engine.LoadViews(ctx, &MyOutput{})

Minimal DQL Flow

engine := shape.New(
    shape.WithCompiler(compile.New()),
    shape.WithLoader(load.New()),
    shape.WithName("/v1/api/report"),
)

component, err := engine.LoadDQLComponent(ctx, "SELECT id FROM ORDERS t")

DQL Directives

shape recognizes three directive forms in DQL:

• #set(...): contract declarations (legacy-compatible).
• #define(...): contract declarations (alias of #set(...) for clearer intent).
• #settings(...) / #setting(...): runtime/settings directives.

Runtime/settings directives currently support:

• #settings($_ = $package('module/path'))
• #settings($_ = $import('alias', 'github.com/acme/pkg'))
• #settings($_ = $meta('docs/path.md'))
• #settings($_ = $cache(true, '5m'))
• #settings($_ = $mcp('tool.name', 'description', 'docs/mcp/tool.md'))
• #settings($_ = $connector('analytics')) (default connector for views that do not already declare one)

Column Discovery Policy

Shape compile now exposes column discovery policy for DQL->IR:

• auto (default): require discovery for SELECT * and for views without concrete declared shape.
• on: always mark query views for discovery.
• off: disable discovery; compile fails when discovery is required.

Use shape.WithColumnDiscoveryModeDefault(...) on engine defaults or shape.WithColumnDiscoveryMode(...) as compile option.

Repository Integration

repository/components.go can optionally merge views generated by the shape pipeline during init.

Enable via:

repository.WithShapePipeline(true)

Default is disabled to preserve existing behavior.