@danceroutine/tango-schema 1.3.0 → 1.5.0

package/dist/{model-YLW1ydkV.js → model-BxkSqwrt.js}

@@ -1,6 +1,10 @@
-import { getLogger } from "@danceroutine/tango-core";
+import { getLogger, getLogger as getLogger$1 } from "@danceroutine/tango-core";
 import { z } from "zod";
 import { AsyncLocalStorage } from "node:async_hooks";
+import { existsSync, existsSync as existsSync$1, readFileSync } from "node:fs";
+import { dirname, extname, resolve, resolve as resolve$1 } from "node:path";
+import { createHash } from "node:crypto";
+import { fileURLToPath } from "node:url";
 
 //#region rolldown:runtime
 var __defProp = Object.defineProperty;
@@ -55,7 +59,7 @@ const warnedDecoratorKinds = new Set();
 function warnDeprecatedSchemaOverload(kind, replacement) {
 	if (warnedDecoratorKinds.has(kind)) return;
 	warnedDecoratorKinds.add(kind);
-	getLogger("tango.schema.decorators").warn(`Deprecated positional schema overload used for t.${kind}(...). Prefer ${replacement} instead.`);
+	getLogger$1("tango.schema.decorators").warn(`Deprecated positional schema overload used for t.${kind}(...). Prefer ${replacement} instead.`);
 }
 function maybeDecorator(schemaOrUndefined, meta) {
 	if (schemaOrUndefined) return decorate(schemaOrUndefined, meta);
@@ -622,24 +626,20 @@ function deriveTableName(name) {
 
 //#endregion
 //#region src/model/internal/InternalSchemaModel.ts
+const REGISTRY_OWNER_KEY = Symbol.for("tango.schema.registryOwner");
+const NORMALIZED_RELATIONS_KEY = Symbol.for("tango.schema.normalizedRelations");
+const EXPLICIT_FIELDS_KEY = Symbol.for("tango.schema.explicitFields");
+const EXPLICIT_RELATIONS_KEY = Symbol.for("tango.schema.explicitRelations");
 var InternalSchemaModel = class InternalSchemaModel {
 	static BRAND = "tango.schema.internal_schema_model";
 	__tangoBrand = InternalSchemaModel.BRAND;
 	metadata;
 	schema;
 	hooks;
-	registry;
-	normalizedRelations;
-	explicitFields;
-	explicitRelations;
-	constructor(registry, metadata, schema, hooks, normalizedRelations, explicitFields, explicitRelations) {
-		this.registry = registry;
+	constructor(metadata, schema, hooks) {
 		this.metadata = metadata;
 		this.schema = schema;
 		this.hooks = hooks;
-		this.normalizedRelations = Object.freeze([...normalizedRelations]);
-		this.explicitFields = explicitFields ? Object.freeze([...explicitFields]) : undefined;
-		this.explicitRelations = explicitRelations;
 	}
 	static create(definition, registry) {
 		InternalSchemaModel.validateDefinition(definition);
@@ -667,22 +667,31 @@ var InternalSchemaModel = class InternalSchemaModel {
 			get: () => registry.getFinalizedFields(key)
 		});
 		Object.freeze(metadata);
-		return new InternalSchemaModel(registry, metadata, definition.schema, definition.hooks, normalizedRelations, definition.fields, relations);
+		const model = new InternalSchemaModel(metadata, definition.schema, definition.hooks);
+		InternalSchemaModel.attachInternals(model, {
+			registry,
+			normalizedRelations,
+			explicitFields: definition.fields,
+			explicitRelations: relations
+		});
+		return model;
 	}
 	static isInternalSchemaModel(value) {
 		return typeof value === "object" && value !== null && value.__tangoBrand === InternalSchemaModel.BRAND;
 	}
 	static getRegistryOwner(model) {
-		return InternalSchemaModel.require(model).registry;
+		const owner = InternalSchemaModel.carrier(model)[REGISTRY_OWNER_KEY];
+		if (!owner) throw new Error(`Model '${model.metadata.key}' is missing internal registry ownership metadata.`);
+		return owner;
 	}
 	static getNormalizedRelations(model) {
-		return InternalSchemaModel.require(model).normalizedRelations;
+		return InternalSchemaModel.carrier(model)[NORMALIZED_RELATIONS_KEY] ?? [];
 	}
 	static getExplicitFields(model) {
-		return InternalSchemaModel.require(model).explicitFields;
+		return InternalSchemaModel.carrier(model)[EXPLICIT_FIELDS_KEY];
 	}
 	static getExplicitRelations(model) {
-		return InternalSchemaModel.require(model).explicitRelations;
+		return InternalSchemaModel.carrier(model)[EXPLICIT_RELATIONS_KEY];
 	}
 	static validateDefinition(definition) {
 		if (!definition.namespace.trim()) throw new Error("Model.namespace is required and cannot be empty.");
@@ -693,6 +702,38 @@ var InternalSchemaModel = class InternalSchemaModel {
 		if (!InternalSchemaModel.isInternalSchemaModel(model)) throw new Error(`Model '${model.metadata.key}' is missing internal registry ownership metadata.`);
 		return model;
 	}
+	static carrier(model) {
+		return InternalSchemaModel.require(model);
+	}
+	static attachInternals(model, internals) {
+		const carrier = model;
+		Object.defineProperties(carrier, {
+			[REGISTRY_OWNER_KEY]: {
+				value: internals.registry,
+				enumerable: false,
+				configurable: false,
+				writable: false
+			},
+			[NORMALIZED_RELATIONS_KEY]: {
+				value: Object.freeze([...internals.normalizedRelations]),
+				enumerable: false,
+				configurable: false,
+				writable: false
+			},
+			[EXPLICIT_FIELDS_KEY]: {
+				value: internals.explicitFields ? Object.freeze([...internals.explicitFields]) : undefined,
+				enumerable: false,
+				configurable: false,
+				writable: false
+			},
+			[EXPLICIT_RELATIONS_KEY]: {
+				value: internals.explicitRelations,
+				enumerable: false,
+				configurable: false,
+				writable: false
+			}
+		});
+	}
 };
 
 //#endregion
@@ -742,6 +783,33 @@ var ResolvedRelationGraphBuilder = class ResolvedRelationGraphBuilder {
 		return new ResolvedRelationGraphBuilder(options).build();
 	}
 	/**
+	* Serialize a resolved graph into the canonical snapshot shape used by
+	* relation-registry code generation and fingerprinting.
+	*/
+	static createSnapshot(graph) {
+		return { models: Array.from(graph.byModel.entries()).sort(([left], [right]) => left.localeCompare(right)).map(([key, relations]) => ({
+			key,
+			relations: Array.from(relations.values()).sort((left, right) => left.name.localeCompare(right.name)).map((relation) => ({
+				edgeId: relation.edgeId,
+				sourceModelKey: relation.sourceModelKey,
+				targetModelKey: relation.targetModelKey,
+				name: relation.name,
+				inverseEdgeId: relation.inverseEdgeId,
+				kind: relation.kind,
+				storageStrategy: relation.storageStrategy,
+				cardinality: relation.cardinality,
+				localFieldName: relation.localFieldName,
+				targetFieldName: relation.targetFieldName,
+				alias: relation.alias,
+				capabilities: {
+					migratable: relation.capabilities.migratable,
+					queryable: relation.capabilities.queryable,
+					hydratable: relation.capabilities.hydratable
+				}
+			}))
+		})) };
+	}
+	/**
 	* Resolve every model's normalized relation descriptors into a single
 	* registry-scoped graph and fail when authoring ambiguity remains.
 	*/
@@ -868,34 +936,58 @@ var ResolvedRelationGraphBuilder = class ResolvedRelationGraphBuilder {
 	}
 };
 
+//#endregion
+//#region src/model/registry/GeneratedRelationRegistryArtifact.ts
+const GENERATED_RELATION_REGISTRY_DIRNAME = ".tango";
+const GENERATED_RELATION_REGISTRY_TYPES_FILENAME = "relations.generated.d.ts";
+const GENERATED_RELATION_REGISTRY_METADATA_FILENAME = "relations.generated.json";
+const GENERATED_RELATION_REGISTRY_METADATA_VERSION = 1;
+
+//#endregion
+//#region src/model/registry/ResolvedRelationGraphArtifactFactory.ts
+var ResolvedRelationGraphArtifactFactory = class ResolvedRelationGraphArtifactFactory {
+	static createSnapshot(graph) {
+		return ResolvedRelationGraphBuilder.createSnapshot(graph);
+	}
+	static createFingerprint(value) {
+		const snapshot = "byModel" in value ? ResolvedRelationGraphArtifactFactory.createSnapshot(value) : value;
+		return createHash("sha256").update(JSON.stringify(snapshot)).digest("hex");
+	}
+};
+
 //#endregion
 //#region src/model/registry/ModelRegistry.ts
 const DEFAULT_IDENTIFIER_NAME = "id";
-const activeRegistryStorage = new AsyncLocalStorage();
+const ACTIVE_REGISTRY_STORAGE_KEY = Symbol.for("tango.schema.activeRegistryStorage");
 var ModelRegistry = class ModelRegistry {
 	static globalRegistry;
 	models = new Map();
 	version = 0;
 	storageCache;
 	relationGraphCache;
+	lastRelationRegistryDriftCheckVersion;
 	/**
-	* Return the shared process-wide registry used by `Model(...)`.
+	* Return the shared default registry used by `Model(...)` for this schema
+	* package instance.
 	*/
 	static global() {
-		if (!ModelRegistry.globalRegistry) ModelRegistry.globalRegistry = new ModelRegistry();
+		ModelRegistry.globalRegistry ??= new ModelRegistry();
 		return ModelRegistry.globalRegistry;
 	}
 	/**
 	* Return the registry currently bound to model construction work.
+	*
+	* This explicit binding is process-shared so code that imports separate
+	* schema package copies can still participate in one construction flow.
 	*/
 	static active() {
-		return activeRegistryStorage.getStore() ?? ModelRegistry.global();
+		return ModelRegistry.activeRegistryStorage().getStore() ?? ModelRegistry.global();
 	}
 	/**
 	* Run work with a specific registry bound as the active construction target.
 	*/
 	static async runWithRegistry(registry, work) {
-		return await activeRegistryStorage.run(registry, work);
+		return await ModelRegistry.activeRegistryStorage().run(registry, work);
 	}
 	/**
 	* Register a model on the shared global registry.
@@ -939,6 +1031,14 @@ var ModelRegistry = class ModelRegistry {
 	static getOwner(model) {
 		return InternalSchemaModel.getRegistryOwner(model);
 	}
+	static runtimeGlobal() {
+		return globalThis;
+	}
+	static activeRegistryStorage() {
+		const runtimeGlobal = ModelRegistry.runtimeGlobal();
+		if (!runtimeGlobal[ACTIVE_REGISTRY_STORAGE_KEY]) runtimeGlobal[ACTIVE_REGISTRY_STORAGE_KEY] = new AsyncLocalStorage();
+		return runtimeGlobal[ACTIVE_REGISTRY_STORAGE_KEY];
+	}
 	/**
 	* Register a model on this registry instance.
 	*/
@@ -1039,9 +1139,22 @@ var ModelRegistry = class ModelRegistry {
 			resolveRef: (ref) => this.resolveRef(ref)
 		});
 		this.relationGraphCache = finalized;
+		this.warnOnGeneratedRelationRegistryDrift(finalized);
 		return finalized;
 	}
 	/**
+	* Return a canonical snapshot of the resolved relation graph.
+	*/
+	getResolvedRelationGraphSnapshot() {
+		return ResolvedRelationGraphArtifactFactory.createSnapshot(this.getResolvedRelationGraph());
+	}
+	/**
+	* Return a deterministic fingerprint for the resolved relation graph.
+	*/
+	getResolvedRelationGraphFingerprint() {
+		return ResolvedRelationGraphArtifactFactory.createFingerprint(this.getResolvedRelationGraph());
+	}
+	/**
 	* Remove all registered models from this registry instance.
 	*/
 	clear() {
@@ -1058,6 +1171,7 @@ var ModelRegistry = class ModelRegistry {
 		this.version += 1;
 		this.storageCache = undefined;
 		this.relationGraphCache = undefined;
+		this.lastRelationRegistryDriftCheckVersion = undefined;
 	}
 	freezeFields(fields) {
 		return Object.freeze(fields.map((field$1) => Object.freeze({ ...field$1 })));
@@ -1077,12 +1191,85 @@ var ModelRegistry = class ModelRegistry {
 		for (const explicitField of explicitFields) mergedFields.set(explicitField.name, explicitField);
 		return Array.from(mergedFields.values());
 	}
+	warnOnGeneratedRelationRegistryDrift(graph) {
+		if (this.lastRelationRegistryDriftCheckVersion === this.version || !this.shouldCheckGeneratedRelationRegistry()) return;
+		this.lastRelationRegistryDriftCheckVersion = this.version;
+		const expected = this.readGeneratedRelationRegistryArtifact();
+		if (!expected) return;
+		const liveSnapshot = ResolvedRelationGraphArtifactFactory.createSnapshot(graph);
+		if (this.isPartialRegistrySnapshot(liveSnapshot, expected.snapshot)) return;
+		const liveFingerprint = ResolvedRelationGraphArtifactFactory.createFingerprint(liveSnapshot);
+		if (liveFingerprint === expected.fingerprint) return;
+		getLogger("tango.schema.registry").warn(`Generated relation registry drift detected. Run 'tango codegen relations' to refresh ${GENERATED_RELATION_REGISTRY_DIRNAME}/${GENERATED_RELATION_REGISTRY_METADATA_FILENAME}.`);
+	}
+	shouldCheckGeneratedRelationRegistry() {
+		return process.env.NODE_ENV === "development" || process.env.NODE_ENV === "test";
+	}
+	readGeneratedRelationRegistryArtifact() {
+		const metadataPath = resolve$1(process.cwd(), GENERATED_RELATION_REGISTRY_DIRNAME, GENERATED_RELATION_REGISTRY_METADATA_FILENAME);
+		if (!existsSync$1(metadataPath)) return undefined;
+		try {
+			const parsed = JSON.parse(readFileSync(metadataPath, "utf8"));
+			if (parsed.version !== GENERATED_RELATION_REGISTRY_METADATA_VERSION || typeof parsed.fingerprint !== "string" || !parsed.snapshot || !Array.isArray(parsed.snapshot.models)) {
+				getLogger("tango.schema.registry").warn(`Ignoring malformed generated relation registry metadata at '${metadataPath}'.`);
+				return undefined;
+			}
+			return parsed;
+		} catch (error) {
+			getLogger("tango.schema.registry").warn(`Unable to read generated relation registry metadata at '${metadataPath}'.`, error);
+			return undefined;
+		}
+	}
+	isPartialRegistrySnapshot(liveSnapshot, expectedSnapshot) {
+		const expectedModels = new Map(expectedSnapshot.models.map((model) => [model.key, model]));
+		if (liveSnapshot.models.some((model) => !expectedModels.has(model.key))) return false;
+		if (liveSnapshot.models.length >= expectedSnapshot.models.length) return false;
+		for (const model of liveSnapshot.models) {
+			const expectedModel = expectedModels.get(model.key);
+			if (JSON.stringify(model.relations) !== JSON.stringify(expectedModel.relations)) return false;
+		}
+		return true;
+	}
 };
 
+//#endregion
+//#region src/resolveSchemaModuleEntrypoint.ts
+const LOCAL_ENTRYPOINT_CANDIDATES = ["./index.ts", "./index.js"];
+function resolveSchemaModuleEntrypoint() {
+	for (const relativePath of LOCAL_ENTRYPOINT_CANDIDATES) {
+		const absolutePath = fileURLToPath(new URL(relativePath, import.meta.url));
+		if (existsSync(absolutePath)) return absolutePath;
+	}
+	throw new Error(`Unable to resolve the @danceroutine/tango-schema entrypoint relative to '${fileURLToPath(import.meta.url)}'.`);
+}
+function createSchemaModuleAliases() {
+	const entrypoint = resolveSchemaModuleEntrypoint();
+	const packageRoot = dirname(entrypoint);
+	const extension = extname(entrypoint);
+	const modelEntrypoint = resolve(packageRoot, "model", `index${extension}`);
+	const domainEntrypoint = resolve(packageRoot, "domain", `index${extension}`);
+	if (!existsSync(modelEntrypoint) || !existsSync(domainEntrypoint)) throw new Error(`Unable to resolve the @danceroutine/tango-schema subpath entrypoints relative to '${entrypoint}'.`);
+	return {
+		"@danceroutine/tango-schema": entrypoint,
+		"@danceroutine/tango-schema/model": modelEntrypoint,
+		"@danceroutine/tango-schema/domain": domainEntrypoint,
+		"@danceroutine/tango-schema/": `${packageRoot}/`
+	};
+}
+
 //#endregion
 //#region src/model/registry/index.ts
 var registry_exports = {};
-__export(registry_exports, { ModelRegistry: () => ModelRegistry });
+__export(registry_exports, {
+	GENERATED_RELATION_REGISTRY_DIRNAME: () => GENERATED_RELATION_REGISTRY_DIRNAME,
+	GENERATED_RELATION_REGISTRY_METADATA_FILENAME: () => GENERATED_RELATION_REGISTRY_METADATA_FILENAME,
+	GENERATED_RELATION_REGISTRY_METADATA_VERSION: () => GENERATED_RELATION_REGISTRY_METADATA_VERSION,
+	GENERATED_RELATION_REGISTRY_TYPES_FILENAME: () => GENERATED_RELATION_REGISTRY_TYPES_FILENAME,
+	ModelRegistry: () => ModelRegistry,
+	ResolvedRelationGraphArtifactFactory: () => ResolvedRelationGraphArtifactFactory,
+	createSchemaModuleAliases: () => createSchemaModuleAliases,
+	resolveSchemaModuleEntrypoint: () => resolveSchemaModuleEntrypoint
+});
 
 //#endregion
 //#region src/model/relations/index.ts
@@ -1119,14 +1306,20 @@ var model_exports = {};
 __export(model_exports, {
 	Constraints: () => Constraints,
 	Decorators: () => Decorators,
+	GENERATED_RELATION_REGISTRY_DIRNAME: () => GENERATED_RELATION_REGISTRY_DIRNAME,
+	GENERATED_RELATION_REGISTRY_METADATA_FILENAME: () => GENERATED_RELATION_REGISTRY_METADATA_FILENAME,
+	GENERATED_RELATION_REGISTRY_METADATA_VERSION: () => GENERATED_RELATION_REGISTRY_METADATA_VERSION,
+	GENERATED_RELATION_REGISTRY_TYPES_FILENAME: () => GENERATED_RELATION_REGISTRY_TYPES_FILENAME,
 	Indexes: () => Indexes,
 	InternalDecoratedFieldKind: () => InternalDecoratedFieldKind,
 	Meta: () => Meta,
 	Model: () => Model,
 	ModelRegistry: () => ModelRegistry,
 	RelationBuilder: () => RelationBuilder,
+	ResolvedRelationGraphArtifactFactory: () => ResolvedRelationGraphArtifactFactory,
 	c: () => Constraints,
 	constraints: () => constraints_exports,
+	createSchemaModuleAliases: () => createSchemaModuleAliases,
 	createTypedModelRef: () => createTypedModelRef,
 	decorators: () => decorators_exports,
 	i: () => Indexes,
@@ -1136,9 +1329,10 @@ __export(model_exports, {
 	registerModelAugmentor: () => registerModelAugmentor,
 	registry: () => registry_exports,
 	relations: () => relations_exports,
+	resolveSchemaModuleEntrypoint: () => resolveSchemaModuleEntrypoint,
 	t: () => Decorators
 });
 
 //#endregion
-export { Constraints, Decorators, Indexes, InternalDecoratedFieldKind, Meta, Model, ModelRegistry, RelationBuilder, constraints_exports, createTypedModelRef, decorators_exports, isTypedModelRef, meta_exports, model_exports, registerModelAugmentor, registry_exports, relations_exports };
-//# sourceMappingURL=model-YLW1ydkV.js.map
+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_exports, createSchemaModuleAliases, createTypedModelRef, decorators_exports, isTypedModelRef, meta_exports, model_exports, registerModelAugmentor, registry_exports, relations_exports, resolveSchemaModuleEntrypoint };
+//# sourceMappingURL=model-BxkSqwrt.js.map