@danceroutine/tango-schema 1.7.0 → 1.8.1

package/dist/domain/internal/InternalReferentialAction.d.ts

@@ -0,0 +1,6 @@
+export declare const InternalReferentialAction: {
+    readonly CASCADE: "CASCADE";
+    readonly SET_NULL: "SET NULL";
+    readonly RESTRICT: "RESTRICT";
+    readonly NO_ACTION: "NO ACTION";
+};

package/dist/index.d.ts

@@ -5,5 +5,5 @@
 export * as domain from './domain/index';
 export * as model from './model/index';
 export type { DeleteReferentialAction, Field, FieldType, IndexDef, ModelHookModel, ModelKeyOf, ModelAugmentations, ModelMetadata, PersistedModelOutput, ModelWriteHookManager, ModelWriteHooks, BeforeCreateHookArgs, AfterCreateHookArgs, BeforeUpdateHookArgs, AfterUpdateHookArgs, BeforeDeleteHookArgs, AfterDeleteHookArgs, BeforeBulkCreateHookArgs, AfterBulkCreateHookArgs, RelationDef, RelationType, UpdateReferentialAction, } from './domain/index';
-export { Model, RelationBuilder, ModelRegistry, GENERATED_RELATION_REGISTRY_DIRNAME, GENERATED_RELATION_REGISTRY_METADATA_FILENAME, GENERATED_RELATION_REGISTRY_METADATA_VERSION, GENERATED_RELATION_REGISTRY_TYPES_FILENAME, ResolvedRelationGraphArtifactFactory, registerModelAugmentor, Constraints, Decorators, Indexes, Meta, c, i, m, t, type ModelDefinition, type ForeignKeyDecoratorConfig, type FieldDecoratorBuilder, type DecoratedFieldKind, type ManyToManyDecoratorConfig, type ModelRef, type ModelRefTarget, type GeneratedRelationRegistryArtifact, type OneToOneDecoratorConfig, type RelationDecoratedSchema, type ResolvedRelationGraphSnapshot, type ResolvedRelationGraphSnapshotModel, type ResolvedRelationGraphSnapshotRelation, type TypedModelRef, } from './model/index';
+export { Model, RelationBuilder, ModelRegistry, ImplicitManyToManyIdentifier, GENERATED_RELATION_REGISTRY_DIRNAME, GENERATED_RELATION_REGISTRY_METADATA_FILENAME, GENERATED_RELATION_REGISTRY_METADATA_VERSION, GENERATED_RELATION_REGISTRY_TYPES_FILENAME, ResolvedRelationGraphArtifactFactory, registerModelAugmentor, Constraints, Decorators, Indexes, Meta, c, i, m, t, type ModelDefinition, type ForeignKeyDecoratorConfig, type FieldDecoratorBuilder, type DecoratedFieldKind, type ManyToManyDecoratorConfig, type ModelRef, type ModelRefTarget, type GeneratedRelationRegistryArtifact, type OneToOneDecoratorConfig, type RelationDecoratedSchema, type ResolvedRelationGraphSnapshot, type ResolvedRelationGraphSnapshotModel, type ResolvedRelationGraphSnapshotRelation, type TypedModelRef, } from './model/index';
 export { createSchemaModuleAliases, resolveSchemaModuleEntrypoint } from './resolveSchemaModuleEntrypoint';

package/dist/index.js

@@ -1,4 +1,4 @@
-import { Constraints, Decorators, GENERATED_RELATION_REGISTRY_DIRNAME, GENERATED_RELATION_REGISTRY_METADATA_FILENAME, GENERATED_RELATION_REGISTRY_METADATA_VERSION, GENERATED_RELATION_REGISTRY_TYPES_FILENAME, Indexes, Meta, Model, ModelRegistry, RelationBuilder, ResolvedRelationGraphArtifactFactory, createSchemaModuleAliases, model_exports, registerModelAugmentor, resolveSchemaModuleEntrypoint } from "./model-BxkSqwrt.js";
+import { Constraints, Decorators, GENERATED_RELATION_REGISTRY_DIRNAME, GENERATED_RELATION_REGISTRY_METADATA_FILENAME, GENERATED_RELATION_REGISTRY_METADATA_VERSION, GENERATED_RELATION_REGISTRY_TYPES_FILENAME, ImplicitManyToManyIdentifier, Indexes, Meta, Model, ModelRegistry, RelationBuilder, ResolvedRelationGraphArtifactFactory, createSchemaModuleAliases, model_exports, registerModelAugmentor, resolveSchemaModuleEntrypoint } from "./model-upj6jxaK.js";
 import { domain_exports } from "./domain-Cufz6y1q.js";
 
-export { Constraints, Decorators, GENERATED_RELATION_REGISTRY_DIRNAME, GENERATED_RELATION_REGISTRY_METADATA_FILENAME, GENERATED_RELATION_REGISTRY_METADATA_VERSION, GENERATED_RELATION_REGISTRY_TYPES_FILENAME, Indexes, Meta, Model, ModelRegistry, RelationBuilder, ResolvedRelationGraphArtifactFactory, Constraints as c, createSchemaModuleAliases, domain_exports as domain, Indexes as i, Meta as m, model_exports as model, registerModelAugmentor, resolveSchemaModuleEntrypoint, Decorators as t };
+export { Constraints, Decorators, GENERATED_RELATION_REGISTRY_DIRNAME, GENERATED_RELATION_REGISTRY_METADATA_FILENAME, GENERATED_RELATION_REGISTRY_METADATA_VERSION, GENERATED_RELATION_REGISTRY_TYPES_FILENAME, ImplicitManyToManyIdentifier, Indexes, Meta, Model, ModelRegistry, RelationBuilder, ResolvedRelationGraphArtifactFactory, Constraints as c, createSchemaModuleAliases, domain_exports as domain, Indexes as i, Meta as m, model_exports as model, registerModelAugmentor, resolveSchemaModuleEntrypoint, Decorators as t };

package/dist/model/decorators/domain/RelationDecoratorConfig.d.ts

@@ -1,5 +1,6 @@
 import type { ZodTypeAny } from './ZodTypeAny';
 import type { ReferentialOptions } from './TangoFieldMeta';
+import type { ModelRef } from './ModelRef';
 /**
  * Config object for `t.foreignKey(...)`.
  *
@@ -32,4 +33,7 @@ export interface ManyToManyDecoratorConfig<TField extends ZodTypeAny = ZodTypeAn
     field?: TField;
     name?: string;
     relatedName?: never;
+    through?: ModelRef;
+    throughSourceFieldName?: string;
+    throughTargetFieldName?: string;
 }

package/dist/model/decorators/domain/TangoFieldMeta.d.ts

@@ -1,30 +1,89 @@
 import type { DeleteReferentialAction, UpdateReferentialAction } from '../../../domain';
 import type { DecoratedFieldKind } from './DecoratedFieldKind';
 import type { ModelRef } from './ModelRef';
+/**
+ * Options attached to a {@link TangoFieldMeta.references} block for foreign-key-style fields.
+ */
 export interface ReferentialOptions {
+    /**
+     * Column on the **referenced** model that this link targets. When omitted, the target model’s
+     * primary key is used.
+     */
     column?: string;
+    /** `ON DELETE` action for the underlying foreign key constraint. */
     onDelete?: DeleteReferentialAction;
+    /** `ON UPDATE` action for the underlying foreign key constraint. */
     onUpdate?: UpdateReferentialAction;
 }
+/**
+ * Field-level metadata attached to a Zod schema via decorators. Migrations and relation wiring
+ * read this shape when inferring columns, constraints, and graph edges.
+ */
 export interface TangoFieldMeta {
+    /** Marks the backing column as the table primary key. */
     primaryKey?: boolean;
+    /** Adds a uniqueness constraint at the database layer. */
     unique?: boolean;
+    /** `NOT NULL` for the stored column when applicable. */
     notNull?: boolean;
+    /** Creates a btree index on the stored column. */
     dbIndex?: boolean;
+    /**
+     * Database column name. When set, migrations and DDL use this instead of the object property
+     * name.
+     */
     dbColumn?: string;
+    /**
+     * Application-level default used by schema inference and validation (`DEFAULT` clause is
+     * derived separately unless {@link dbDefault} is set).
+     */
     default?: string | {
         now: true;
     } | null;
+    /** Raw SQL expression for the column’s `DEFAULT` in generated DDL. */
     dbDefault?: string;
+    /** Human-oriented description for forms, admin UIs, and generated docs. */
     helpText?: string;
+    /** Enumerated allowed values when the field is presented as a choice list. */
     choices?: readonly unknown[];
+    /** Runtime validators applied when coercing or checking incoming values. */
     validators?: readonly ((value: unknown) => unknown)[];
+    /** Map of validator key to user-facing error message overrides. */
     errorMessages?: Record<string, string>;
+    /**
+     * Declares how this field relates to another model: plain FK (`target`), optional explicit
+     * many-to-many through model (`through`), and the through-side field names that pair the source
+     * and target endpoints.
+     */
     references?: {
+        /** Symbolic reference to the related model (same resolution rules as elsewhere in schema). */
         target: ModelRef;
         options?: ReferentialOptions;
+        /** Explicit join model for a many-to-many when not using an implicit through table. */
+        through?: ModelRef;
+        /**
+         * Schema field key on the through model that holds the foreign key **from** this model’s
+         * side of the association.
+         */
+        throughSourceFieldName?: string;
+        /**
+         * Schema field key on the through model that holds the foreign key **to** the related
+         * model’s side of the association.
+         */
+        throughTargetFieldName?: string;
     };
+    /**
+     * Classifies decorated relation endpoints (`foreignKey`, `oneToOne`, `manyToMany`) for
+     * normalization and graph construction.
+     */
     relationKind?: DecoratedFieldKind;
+    /**
+     * Preferred name for the forward edge from this model toward {@link references.target}
+     * (overrides inferred naming).
+     */
     forwardName?: string;
+    /**
+     * Preferred name for the reverse edge back from the related model (overrides inferred naming).
+     */
     reverseName?: string;
 }

package/dist/model/index.d.ts

@@ -12,6 +12,7 @@ export * as registry from './registry/index';
 export * as relations from './relations/index';
 export type { ModelDefinition } from './ModelDefinition';
 export { RelationBuilder } from './relations/index';
+export { ImplicitManyToManyIdentifier } from './relations/ImplicitManyToManyIdentifier';
 export { Model } from './Model';
 export { registerModelAugmentor } from './ModelAugmentorRegistry';
 export { Decorators, t } from './decorators/index';

package/dist/model/index.js

@@ -1,3 +1,3 @@
-import { Constraints, Decorators, GENERATED_RELATION_REGISTRY_DIRNAME, GENERATED_RELATION_REGISTRY_METADATA_FILENAME, GENERATED_RELATION_REGISTRY_METADATA_VERSION, GENERATED_RELATION_REGISTRY_TYPES_FILENAME, Indexes, InternalDecoratedFieldKind, Meta, Model, ModelRegistry, RelationBuilder, ResolvedRelationGraphArtifactFactory, constraints_exports, createSchemaModuleAliases, createTypedModelRef, decorators_exports, isTypedModelRef, meta_exports, registerModelAugmentor, registry_exports, relations_exports, resolveSchemaModuleEntrypoint } from "../model-BxkSqwrt.js";
+import { Constraints, Decorators, GENERATED_RELATION_REGISTRY_DIRNAME, GENERATED_RELATION_REGISTRY_METADATA_FILENAME, GENERATED_RELATION_REGISTRY_METADATA_VERSION, GENERATED_RELATION_REGISTRY_TYPES_FILENAME, ImplicitManyToManyIdentifier, Indexes, InternalDecoratedFieldKind, Meta, Model, ModelRegistry, RelationBuilder, ResolvedRelationGraphArtifactFactory, constraints_exports, createSchemaModuleAliases, createTypedModelRef, decorators_exports, isTypedModelRef, meta_exports, registerModelAugmentor, registry_exports, relations_exports, resolveSchemaModuleEntrypoint } from "../model-upj6jxaK.js";
 
-export { Constraints, Decorators, GENERATED_RELATION_REGISTRY_DIRNAME, GENERATED_RELATION_REGISTRY_METADATA_FILENAME, GENERATED_RELATION_REGISTRY_METADATA_VERSION, GENERATED_RELATION_REGISTRY_TYPES_FILENAME, Indexes, InternalDecoratedFieldKind, Meta, Model, ModelRegistry, RelationBuilder, ResolvedRelationGraphArtifactFactory, Constraints as c, constraints_exports as constraints, createSchemaModuleAliases, createTypedModelRef, decorators_exports as decorators, Indexes as i, isTypedModelRef, Meta as m, meta_exports as meta, registerModelAugmentor, registry_exports as registry, relations_exports as relations, resolveSchemaModuleEntrypoint, Decorators as t };
+export { Constraints, Decorators, GENERATED_RELATION_REGISTRY_DIRNAME, GENERATED_RELATION_REGISTRY_METADATA_FILENAME, GENERATED_RELATION_REGISTRY_METADATA_VERSION, GENERATED_RELATION_REGISTRY_TYPES_FILENAME, ImplicitManyToManyIdentifier, Indexes, InternalDecoratedFieldKind, Meta, Model, ModelRegistry, RelationBuilder, ResolvedRelationGraphArtifactFactory, Constraints as c, constraints_exports as constraints, createSchemaModuleAliases, createTypedModelRef, decorators_exports as decorators, Indexes as i, isTypedModelRef, Meta as m, meta_exports as meta, registerModelAugmentor, registry_exports as registry, relations_exports as relations, resolveSchemaModuleEntrypoint, Decorators as t };

package/dist/model/registry/ModelRegistry.d.ts

@@ -118,6 +118,7 @@ export declare class ModelRegistry {
      */
     values(): readonly Model[];
     private bumpVersion;
+    private stripImplicitManyToManyModels;
     private freezeFields;
     private inferPrimaryKeyName;
     private mergeStorageFields;

package/dist/model/registry/ResolvedRelationGraphSnapshot.d.ts

@@ -1,26 +1,110 @@
 import type { RelationCardinality, RelationPublicKind, RelationStorageStrategy } from '../relations/RelationSpec';
+/**
+ * Serializable snapshot of a single relation edge from the resolved relation
+ * graph. Snapshots are the stable, build-time wire format consumed by codegen
+ * and by tooling that compares the graph across runs.
+ *
+ * A snapshot row captures both the abstract edge identity (who connects to
+ * whom, under what public name) and the physical storage details (local
+ * fields, join columns, through-model coordinates) needed to translate the
+ * edge into SQL later.
+ */
 export type ResolvedRelationGraphSnapshotRelation = {
+    /**
+     * Stable identifier for this edge within the graph. Used to cross-reference
+     * an edge with its inverse and to detect drift between snapshots.
+     */
     edgeId: string;
+    /** Model key of the endpoint that owns this edge in the resolved graph. */
     sourceModelKey: string;
+    /** Model key of the endpoint this edge points at. */
     targetModelKey: string;
+    /**
+     * Public relation name exposed to application code and query builders
+     * (for example `author` or `tags`).
+     */
     name: string;
+    /**
+     * Identifier of the paired edge on the opposite endpoint, when one exists.
+     * Bidirectional relations populate this; one-way edges leave it unset.
+     */
     inverseEdgeId?: string;
+    /**
+     * Public relation kind (`belongsTo`, `hasMany`, `manyToMany`, ...).
+     */
     kind: RelationPublicKind;
+    /**
+     * How the edge is physically stored. Distinguishes direct foreign-key
+     * references from reverse references and join-table backed relations.
+     */
     storageStrategy: RelationStorageStrategy;
+    /** Whether the edge yields one target (`single`) or many (`many`). */
     cardinality: RelationCardinality;
+    /**
+     * Owner-side column that stores the foreign key, when the edge is backed
+     * by a local reference column.
+     */
     localFieldName?: string;
+    /**
+     * Target-side column the foreign key resolves against, when applicable.
+     */
     targetFieldName?: string;
+    /**
+     * Model key of the synthesized or user-provided through model for
+     * many-to-many edges.
+     */
+    throughModelKey?: string;
+    /** Physical join-table name for many-to-many edges. */
+    throughTable?: string;
+    /** Through-model schema field on the source side, if resolved. */
+    throughSourceFieldName?: string;
+    /** Through-model schema field on the target side, if resolved. */
+    throughTargetFieldName?: string;
+    /**
+     * Physical join-table column that stores the owner-side primary key for
+     * many-to-many edges.
+     */
+    throughSourceKey?: string;
+    /**
+     * Physical join-table column that stores the target-side primary key for
+     * many-to-many edges.
+     */
+    throughTargetKey?: string;
+    /**
+     * Alias used when the edge participates in SQL joins. Derived
+     * deterministically so compiled SQL is stable across runs.
+     */
     alias: string;
+    /**
+     * What this edge is allowed to participate in. The builder uses these
+     * flags to decide whether migrations emit DDL, queries can select over
+     * the edge, and hydration can populate the related attribute.
+     */
     capabilities: {
+        /** Whether migration tooling should emit DDL for this edge. */
         migratable: boolean;
+        /** Whether the edge can appear as a hop in a query path. */
         queryable: boolean;
+        /** Whether hydrators can populate the related attribute on a row. */
         hydratable: boolean;
     };
 };
+/**
+ * Snapshot of one model's relation edges. Grouping edges by source model
+ * lets codegen walk the graph model-by-model without having to re-index.
+ */
 export type ResolvedRelationGraphSnapshotModel = {
+    /** Model key these relations source from. */
     key: string;
+    /** Resolved outgoing relation edges in registration order. */
     relations: ResolvedRelationGraphSnapshotRelation[];
 };
+/**
+ * Top-level serializable snapshot of the resolved relation graph for a
+ * registry. Written to disk by codegen and diffed across runs to detect
+ * registry drift.
+ */
 export type ResolvedRelationGraphSnapshot = {
+    /** Per-model relation snapshots in registration order. */
     models: ResolvedRelationGraphSnapshotModel[];
 };

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

@@ -0,0 +1,45 @@
+/**
+ * Single source of truth for identity of Tango-synthesized many-to-many
+ * through models. Other parts of the schema package interact with synthesized
+ * models exclusively through this class so they do not have to know the
+ * namespace or digest scheme those keys encode.
+ */
+export declare class ImplicitManyToManyIdentifier {
+    private static readonly NAMESPACE;
+    /**
+     * Stable model key for the synthesized through model connecting
+     * `sourceModelKey` to `targetModelKey` via the schema field
+     * `sourceSchemaFieldKey`.
+     *
+     * The returned key is deterministic across runs so storage and hydration
+     * artifacts stay stable as long as the inputs match.
+     */
+    static getModelKey(sourceModelKey: string, sourceSchemaFieldKey: string, targetModelKey: string): string;
+    /**
+     * Deterministic short digest used to derive the physical join-table name
+     * for a synthesized through model. Shorter than the model-key digest so
+     * table names stay within common SQL identifier limits.
+     */
+    static getTableBaseDigest(sourceModelKey: string, sourceSchemaFieldKey: string, targetModelKey: string): string;
+    /**
+     * True when `modelKey` was produced by {@link getModelKey} and therefore
+     * identifies a synthesized through model. Callers use this instead of
+     * comparing namespace prefixes so the namespace remains an implementation
+     * detail of this class.
+     */
+    static isImplicitManyToManyModel(modelKey: string): boolean;
+    /**
+     * Namespace under which synthesized through models are registered.
+     * Exposed so {@link ImplicitManyToManyThroughFactory} can construct the
+     * model with the correct namespace. External callers that want to ask
+     * "is this an implicit model" should prefer {@link isImplicitManyToManyModel}.
+     */
+    static getNamespace(): string;
+    /**
+     * Extract the `m2m_<digest>` component of a synthesized model key so the
+     * factory can register the through model with a deterministic name while
+     * keeping the namespace owned by this class.
+     */
+    static getModelName(modelKey: string): string;
+    private static digest;
+}

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

@@ -0,0 +1,14 @@
+import type { Model } from '../../domain/index';
+import type { ModelRegistry } from '../registry/ModelRegistry';
+export declare class ImplicitManyToManyThroughFactory {
+    static throughFieldNames(sourceModel: Model, targetModel: Model): {
+        throughSourceFieldName: string;
+        throughTargetFieldName: string;
+    };
+    static buildModels(registry: ModelRegistry): Model[];
+    private static unwrapForForeignKeyField;
+    private static clonePrimaryKeySchemaForForeignKey;
+    private static readSinglePrimaryKey;
+    private static collectImplicitDescriptors;
+    private static allocateTableName;
+}

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

@@ -19,6 +19,12 @@ export interface ResolvedRelationDescriptor {
     cardinality: RelationCardinality;
     localFieldName?: string;
     targetFieldName?: string;
+    throughModelKey?: string;
+    throughTable?: string;
+    throughSourceFieldName?: string;
+    throughTargetFieldName?: string;
+    throughSourceKey?: string;
+    throughTargetKey?: string;
     capabilities: {
         migratable: boolean;
         queryable: boolean;

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

@@ -1,7 +1,7 @@
 import type { Model } from '../../domain/index';
 import type { FinalizedStorageArtifacts } from '../fields/FinalizedStorageArtifacts';
 import type { ResolvedRelationGraphSnapshot } from '../registry/ResolvedRelationGraphSnapshot';
-import type { NormalizedRelationStorageDescriptor } from './NormalizedRelationStorageDescriptor';
+import { type NormalizedRelationStorageDescriptor } from './NormalizedRelationStorageDescriptor';
 import type { ResolvedRelationGraph } from './ResolvedRelationGraph';
 type GraphBuilderOptions = {
     version: number;

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

@@ -9,3 +9,4 @@
 export declare function toSnakeCase(value: string): string;
 export declare function pluralize(value: string): string;
 export declare function deriveTableName(name: string): string;
+export declare function decapitalizeModelName(name: string): string;