@danceroutine/tango-schema 1.1.3 → 1.3.0

package/dist/model/relations/RelationSpec.d.ts

@@ -0,0 +1,48 @@
+export declare const InternalRelationPublicKind: {
+    readonly BELONGS_TO: "belongsTo";
+    readonly HAS_ONE: "hasOne";
+    readonly HAS_MANY: "hasMany";
+    readonly MANY_TO_MANY: "manyToMany";
+};
+export declare const InternalRelationStorageStrategy: {
+    readonly REFERENCE: "reference";
+    readonly REVERSE_REFERENCE: "reverse_reference";
+    readonly MANY_TO_MANY: "many_to_many";
+};
+export declare const InternalRelationCardinality: {
+    readonly SINGLE: "single";
+    readonly MANY: "many";
+};
+export declare const InternalRelationProvenance: {
+    readonly FIELD_DECORATOR: "field-decorator";
+    readonly RELATIONS_API: "relations-api";
+    readonly SYNTHESIZED_REVERSE: "synthesized-reverse";
+};
+export type RelationPublicKind = (typeof InternalRelationPublicKind)[keyof typeof InternalRelationPublicKind];
+export type RelationStorageStrategy = (typeof InternalRelationStorageStrategy)[keyof typeof InternalRelationStorageStrategy];
+export type RelationCardinality = (typeof InternalRelationCardinality)[keyof typeof InternalRelationCardinality];
+export type RelationProvenance = (typeof InternalRelationProvenance)[keyof typeof InternalRelationProvenance];
+/**
+ * Author-time relation intent after target resolution but before full graph
+ * pairing and naming.
+ *
+ * This type is the conceptual bridge between normalized descriptors and the
+ * fully resolved graph. It exists so the relations subdomain has a stable
+ * vocabulary for relation kinds, storage strategies, and provenance as the
+ * pipeline becomes more sophisticated.
+ */
+export interface RelationSpec {
+    edgeId: string;
+    sourceModelKey: string;
+    sourceSchemaFieldKey?: string;
+    targetModelKey: string;
+    kind: RelationPublicKind;
+    storageStrategy: RelationStorageStrategy;
+    localFieldName?: string;
+    targetFieldName?: string;
+    nameHint?: string;
+    throughModelKey?: string;
+    throughSourceFieldName?: string;
+    throughTargetFieldName?: string;
+    provenance: RelationProvenance;
+}

package/dist/model/relations/ResolvedRelationGraph.d.ts

@@ -0,0 +1,43 @@
+import type { RelationCardinality, RelationProvenance, RelationStorageStrategy, RelationPublicKind } from './RelationSpec';
+/**
+ * Fully resolved relation edge published by the registry after storage
+ * artifacts are finalized.
+ *
+ * This is the resolution-stage shape consumed by ORM-facing relation metadata.
+ * Each descriptor has final naming, cardinality, key mapping, and capability
+ * flags that describe whether the edge is currently migratable, queryable, and
+ * hydratable.
+ */
+export interface ResolvedRelationDescriptor {
+    edgeId: string;
+    sourceModelKey: string;
+    targetModelKey: string;
+    name: string;
+    inverseEdgeId?: string;
+    kind: RelationPublicKind;
+    storageStrategy: RelationStorageStrategy;
+    cardinality: RelationCardinality;
+    localFieldName?: string;
+    targetFieldName?: string;
+    capabilities: {
+        migratable: boolean;
+        queryable: boolean;
+        hydratable: boolean;
+    };
+    provenance: RelationProvenance;
+    alias: string;
+    ambiguity?: string;
+}
+/**
+ * Registry-scoped relation graph built from normalized relation descriptors,
+ * explicit relation names, and finalized storage artifacts.
+ *
+ * This is the canonical resolved relation view for query planning and future
+ * hydration work. It is versioned because relation resolution is scoped to a
+ * specific registry snapshot.
+ */
+export interface ResolvedRelationGraph {
+    version: number;
+    byModel: ReadonlyMap<string, ReadonlyMap<string, ResolvedRelationDescriptor>>;
+    byEdgeId: ReadonlyMap<string, ResolvedRelationDescriptor>;
+}

package/dist/model/relations/ResolvedRelationGraphBuilder.d.ts

@@ -0,0 +1,48 @@
+import type { Model } from '../../domain/index';
+import type { FinalizedStorageArtifacts } from '../fields/FinalizedStorageArtifacts';
+import type { NormalizedRelationStorageDescriptor } from './NormalizedRelationStorageDescriptor';
+import type { ResolvedRelationGraph } from './ResolvedRelationGraph';
+type GraphBuilderOptions = {
+    version: number;
+    models: readonly Model[];
+    storage: FinalizedStorageArtifacts;
+    resolveRef: (ref: NormalizedRelationStorageDescriptor['targetRef']) => Model;
+};
+/**
+ * Resolution-stage builder that turns normalized relation descriptors into the
+ * registry-scoped resolved relation graph.
+ *
+ * This is the final pipeline stage in the relations subdomain. It combines:
+ *
+ * - normalized field-authored relation descriptors
+ * - explicit model-level relation names from `RelationBuilder`
+ * - finalized storage artifacts from the registry
+ *
+ * The result is the canonical named relation graph used by ORM-facing
+ * consumers.
+ */
+export declare class ResolvedRelationGraphBuilder {
+    private readonly options;
+    private readonly byModel;
+    private readonly byEdgeId;
+    private readonly matchedOverrides;
+    constructor(options: GraphBuilderOptions);
+    static build(options: GraphBuilderOptions): ResolvedRelationGraph;
+    /**
+     * Resolve every model's normalized relation descriptors into a single
+     * registry-scoped graph and fail when authoring ambiguity remains.
+     */
+    build(): ResolvedRelationGraph;
+    private addModelRelations;
+    private addReferenceRelations;
+    private findForwardOverride;
+    private findReverseOverride;
+    private assertAllOverridesMatched;
+    private addResolvedRelation;
+    private getPrimaryKey;
+    private markOverrideMatched;
+    private buildOverrideMarker;
+    private resolveRelationTargetKey;
+    private deriveReverseName;
+}
+export {};

package/dist/model/relations/SchemaNaming.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Shared naming policy for the model and relations subdomains.
+ *
+ * These helpers are not an authoring or graph stage on their own. They are the
+ * cross-cutting policy layer used by both model construction and relation
+ * resolution when Tango derives table names, aliases, and synthesized relation
+ * names in a Django-style shape.
+ */
+export declare function toSnakeCase(value: string): string;
+export declare function pluralize(value: string): string;
+export declare function deriveTableName(name: string): string;

package/dist/model/relations/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Domain boundary barrel for relation authoring.
+ *
+ * The relations subdomain has three internal layers:
+ *
+ * - authoring: `RelationBuilder`
+ * - normalization: field-authored relations become normalized descriptors
+ * - resolution: normalized descriptors become the registry-scoped relation graph
+ *
+ * Only the authoring surface is exported here. The later pipeline stages stay
+ * internal until Tango intentionally publishes them as supported contracts.
+ */
+export { RelationBuilder } from './RelationBuilder';