@atscript/db 0.1.140 → 0.1.142

package/dist/column-diff-DiBbXyLA.d.cts

@@ -0,0 +1,211 @@
+import { Bt as AtscriptDbView, D as TColumnDiff, Gt as AtscriptQueryFieldRef, I as TDbDefaultValue, Kt as AtscriptQueryNode, R as TDbFieldMeta, X as TDbStorageType, at as TExistingColumn, rt as TDerivedColumn, st as TExistingTableOption, tn as AtscriptDbReadable } from "./buckets-Bv4pah66.cjs";
+
+//#region src/schema/schema-hash.d.ts
+interface TFieldSnapshot {
+  physicalName: string;
+  designType: string;
+  optional: boolean;
+  isPrimaryKey: boolean;
+  storage: TDbStorageType;
+  defaultValue?: TDbDefaultValue;
+  /** Adapter-specific mapped type (e.g., "VARCHAR(255)", "INTEGER"). */
+  mappedType?: string;
+  /** `@db.encrypted` — toggling encryption changes the snapshot hash on every adapter. */
+  encrypted?: boolean;
+  /**
+   * `@db.column.derived` — what the generated column reads (physical JSON
+   * column, path, leaf type). Present for derived fields only, so a table
+   * without one hashes exactly as before; the column diff compares it with
+   * the model to detect an expression change (engines normalize the stored
+   * expression text, so the snapshot is the baseline).
+   * @since 0.1.141
+   */
+  derived?: Omit<TDerivedColumn, "sourcePath">;
+}
+interface TIndexSnapshot {
+  key: string;
+  type: string;
+  fields: Array<{
+    name: string;
+    sort: string;
+  }>;
+}
+interface TForeignKeySnapshot {
+  fields: string[];
+  targetTable: string;
+  targetFields: string[];
+  onDelete?: string;
+  onUpdate?: string;
+}
+interface TTableSnapshot {
+  tableName: string;
+  fields: TFieldSnapshot[];
+  indexes: TIndexSnapshot[];
+  foreignKeys: TForeignKeySnapshot[];
+  /** Adapter-specific table-level options (e.g., MySQL engine/charset, MongoDB capped). */
+  tableOptions?: TExistingTableOption[];
+}
+/**
+ * One join of a managed view as stored in its snapshot.
+ * @since 0.1.128 — `joinTables` elements were bare target-table names before;
+ * the ON predicate is now part of the view definition.
+ */
+interface TViewJoinSnapshot {
+  /**
+   * Scope name of the join: the physical table / view, or the `@db.alias`
+   * type name when the join is aliased (then {@link table} holds the physical name).
+   */
+  targetTable: string;
+  /**
+   * Physical table / view of an aliased join. Emitted only when the target
+   * is a `@db.alias` type — a plain join serializes exactly as before.
+   * @since 0.1.141
+   */
+  table?: string;
+  /** Canonical JSON of the join condition (see {@link canonicalizeQueryNode}). */
+  condition: string;
+  /** Emitted only for `"left"` — an inner join (the default) carries no key. @since 0.1.136 */
+  kind?: "inner" | "left";
+}
+/**
+ * One column of a managed view as stored in its snapshot — the PHYSICAL
+ * source it reads, so a source rename (`@db.column`, flattening, a moved
+ * JSON leaf) or an aggregate change recreates the view.
+ * @since 0.1.136
+ */
+interface TViewColumnSnapshot {
+  column: string;
+  sourceTable: string;
+  sourceColumn: string;
+  /** JSON array of the path segments inside a JSON source column. */
+  jsonPath?: string;
+  jsonType?: string;
+  aggFn?: string;
+  aggField?: string;
+  /** Canonical JSON of a conditional aggregate's predicate. */
+  aggFilter?: string;
+}
+interface TViewSnapshot {
+  tableName: string;
+  viewType: "V" | "M" | "E";
+  entryTable?: string;
+  /**
+   * Joins in declaration order. The key keeps its historical name so a
+   * join-less view (`[]`) serializes byte-identically to older snapshots.
+   */
+  joinTables?: TViewJoinSnapshot[];
+  /** @since 0.1.136 — view columns and their physical sources, sorted by `column`. */
+  columns?: TViewColumnSnapshot[];
+  filterHash?: string;
+  /** @since 0.1.128 — hash of the canonical `@db.view.having` predicate. */
+  havingHash?: string;
+  materialized?: boolean;
+  /**
+   * @since 0.1.137 — the adapter's `viewRenderRevision()`, present only when
+   * the adapter defines one (managed views only).
+   */
+  renderRevision?: string;
+  fields: TFieldSnapshot[];
+}
+/**
+ * Extracts a canonical, serializable snapshot from a readable's metadata.
+ * Sorted deterministically so the hash is stable across runs.
+ *
+ * @param readable - The table/view readable.
+ * @param typeMapper - Optional adapter-specific type mapper. When provided,
+ *   each field's mapped type (e.g., "VARCHAR(255)") is stored in the snapshot
+ *   for precise type change detection.
+ */
+declare function computeTableSnapshot(readable: AtscriptDbReadable, typeMapper?: (field: TDbFieldMeta) => string, tableOptions?: TExistingTableOption[]): TTableSnapshot;
+/**
+ * Extracts a canonical, serializable snapshot from a view's metadata.
+ * Captures view plan (entry table, joins, filter, materialization) for
+ * detecting view definition changes.
+ */
+declare function computeViewSnapshot(view: AtscriptDbView): TViewSnapshot;
+/** Canonical (table-qualified, fixed-key-order) form of a view predicate. */
+type TCanonicalQueryNode = {
+  and: TCanonicalQueryNode[];
+} | {
+  or: TCanonicalQueryNode[];
+} | {
+  not: TCanonicalQueryNode;
+} /** `r` is `{ f: "<table>.<field>" }` for a field-to-field comparison, else the literal. */ | {
+  l: string;
+  op: string;
+  r?: unknown;
+};
+/**
+ * Converts a view predicate (join condition, `@db.view.filter`,
+ * `@db.view.having`) into a serializable structure whose JSON is a stable
+ * function of its MEANING: field refs become `qualify(ref)` — the view's
+ * `resolveFieldRef(ref, (n) => n)`, i.e. `"<table>.<field>"`, so a predicate
+ * retargeted to another table with the same field name changes — operators
+ * and literal values are kept as-is, `$and`/`$or` keep declaration order, and
+ * no function references survive. Two identical models produce byte-identical
+ * JSON.
+ * @since 0.1.128
+ */
+declare function canonicalizeQueryNode(node: AtscriptQueryNode, qualify: (ref: AtscriptQueryFieldRef) => string): TCanonicalQueryNode;
+/**
+ * Computes a deterministic hash string from multiple table snapshots.
+ * Uses FNV-1a for speed — not cryptographic, just needs stability + collision resistance.
+ */
+declare function computeSchemaHash(snapshots: Array<TTableSnapshot | TViewSnapshot>): string;
+/**
+ * Computes a hash for a single table/view snapshot.
+ * Used for per-table change detection via stored snapshots.
+ */
+declare function computeTableHash(snapshot: TTableSnapshot | TViewSnapshot): string;
+/**
+ * Converts stored snapshot fields to `TExistingColumn[]` format
+ * for use with `computeColumnDiff`. Used by adapters that lack
+ * native column introspection (e.g., MongoDB).
+ *
+ * The `type` field uses `mappedType` when available (adapter-specific),
+ * falling back to `designType`. Derived fields are left out (since 0.1.141):
+ * an adapter without column introspection stores no derived column, and a
+ * `physicalName` of one is its SOURCE path — reporting it as an existing
+ * column would have the diff drop the source leaf.
+ *
+ * With `readable`, the subfields of its navigation properties are left out
+ * too: a document adapter's snapshot lists them (for hash stability — see
+ * `snapshotFields`) although nothing is stored under a nav field — they are
+ * not columns to drop.
+ */
+declare function snapshotToExistingColumns(snapshot: TTableSnapshot, readable?: AtscriptDbReadable): TExistingColumn[];
+/**
+ * Extracts table options from a stored snapshot for diff comparison.
+ * Used as fallback when an adapter lacks native table option introspection.
+ */
+declare function snapshotToExistingTableOptions(snapshot: TTableSnapshot): TExistingTableOption[];
+//#endregion
+//#region src/schema/column-diff.d.ts
+/**
+ * Whether a live column's type differs from the type the adapter's
+ * `typeMapper` gives the field — the one rule schema sync diffs column types
+ * by (case-insensitive). Exported for adapters that must agree with it (the
+ * PostgreSQL recreate converts exactly the columns this reports changed).
+ * @since 0.1.137
+ */
+declare function isColumnTypeChanged(existingType: string, expectedType: string): boolean;
+/**
+ * Computes the difference between desired schema fields and existing database columns.
+ *
+ * @param desired - Field descriptors from the Atscript type (after flattening) —
+ *                  the readable's `columnDescriptors`; ignored descriptors are skipped.
+ * @param existing - Columns currently in the database (from introspection).
+ * @param typeMapper - Optional function to map field metadata to DB-native type strings.
+ *                     Receives the full field meta (design type, annotations, PK status, etc.)
+ *                     so adapters can produce context-aware types (e.g., `VARCHAR(255)` from maxLength).
+ *                     Required for type change detection.
+ * @param opts.snapshot - The table's stored snapshot (since 0.1.141) — the baseline a
+ *                        derived column's expression is compared with (the engine normalizes
+ *                        the expression it stores, so the live column cannot be). Without
+ *                        one, only a kind or type drift is seen.
+ */
+declare function computeColumnDiff(desired: readonly TDbFieldMeta[], existing: TExistingColumn[], typeMapper?: (field: TDbFieldMeta) => string, opts?: {
+  snapshot?: TTableSnapshot | null;
+}): TColumnDiff;
+//#endregion
+export { TTableSnapshot as a, TViewSnapshot as c, computeTableHash as d, computeTableSnapshot as f, snapshotToExistingTableOptions as h, TForeignKeySnapshot as i, canonicalizeQueryNode as l, snapshotToExistingColumns as m, isColumnTypeChanged as n, TViewColumnSnapshot as o, computeViewSnapshot as p, TFieldSnapshot as r, TViewJoinSnapshot as s, computeColumnDiff as t, computeSchemaHash as u };

package/dist/column-diff-n-k5KY0u.d.mts

@@ -0,0 +1,211 @@
+import { Bt as AtscriptDbView, D as TColumnDiff, Gt as AtscriptQueryFieldRef, I as TDbDefaultValue, Kt as AtscriptQueryNode, R as TDbFieldMeta, X as TDbStorageType, at as TExistingColumn, rt as TDerivedColumn, st as TExistingTableOption, tn as AtscriptDbReadable } from "./buckets-CjL7F-hp.mjs";
+
+//#region src/schema/schema-hash.d.ts
+interface TFieldSnapshot {
+  physicalName: string;
+  designType: string;
+  optional: boolean;
+  isPrimaryKey: boolean;
+  storage: TDbStorageType;
+  defaultValue?: TDbDefaultValue;
+  /** Adapter-specific mapped type (e.g., "VARCHAR(255)", "INTEGER"). */
+  mappedType?: string;
+  /** `@db.encrypted` — toggling encryption changes the snapshot hash on every adapter. */
+  encrypted?: boolean;
+  /**
+   * `@db.column.derived` — what the generated column reads (physical JSON
+   * column, path, leaf type). Present for derived fields only, so a table
+   * without one hashes exactly as before; the column diff compares it with
+   * the model to detect an expression change (engines normalize the stored
+   * expression text, so the snapshot is the baseline).
+   * @since 0.1.141
+   */
+  derived?: Omit<TDerivedColumn, "sourcePath">;
+}
+interface TIndexSnapshot {
+  key: string;
+  type: string;
+  fields: Array<{
+    name: string;
+    sort: string;
+  }>;
+}
+interface TForeignKeySnapshot {
+  fields: string[];
+  targetTable: string;
+  targetFields: string[];
+  onDelete?: string;
+  onUpdate?: string;
+}
+interface TTableSnapshot {
+  tableName: string;
+  fields: TFieldSnapshot[];
+  indexes: TIndexSnapshot[];
+  foreignKeys: TForeignKeySnapshot[];
+  /** Adapter-specific table-level options (e.g., MySQL engine/charset, MongoDB capped). */
+  tableOptions?: TExistingTableOption[];
+}
+/**
+ * One join of a managed view as stored in its snapshot.
+ * @since 0.1.128 — `joinTables` elements were bare target-table names before;
+ * the ON predicate is now part of the view definition.
+ */
+interface TViewJoinSnapshot {
+  /**
+   * Scope name of the join: the physical table / view, or the `@db.alias`
+   * type name when the join is aliased (then {@link table} holds the physical name).
+   */
+  targetTable: string;
+  /**
+   * Physical table / view of an aliased join. Emitted only when the target
+   * is a `@db.alias` type — a plain join serializes exactly as before.
+   * @since 0.1.141
+   */
+  table?: string;
+  /** Canonical JSON of the join condition (see {@link canonicalizeQueryNode}). */
+  condition: string;
+  /** Emitted only for `"left"` — an inner join (the default) carries no key. @since 0.1.136 */
+  kind?: "inner" | "left";
+}
+/**
+ * One column of a managed view as stored in its snapshot — the PHYSICAL
+ * source it reads, so a source rename (`@db.column`, flattening, a moved
+ * JSON leaf) or an aggregate change recreates the view.
+ * @since 0.1.136
+ */
+interface TViewColumnSnapshot {
+  column: string;
+  sourceTable: string;
+  sourceColumn: string;
+  /** JSON array of the path segments inside a JSON source column. */
+  jsonPath?: string;
+  jsonType?: string;
+  aggFn?: string;
+  aggField?: string;
+  /** Canonical JSON of a conditional aggregate's predicate. */
+  aggFilter?: string;
+}
+interface TViewSnapshot {
+  tableName: string;
+  viewType: "V" | "M" | "E";
+  entryTable?: string;
+  /**
+   * Joins in declaration order. The key keeps its historical name so a
+   * join-less view (`[]`) serializes byte-identically to older snapshots.
+   */
+  joinTables?: TViewJoinSnapshot[];
+  /** @since 0.1.136 — view columns and their physical sources, sorted by `column`. */
+  columns?: TViewColumnSnapshot[];
+  filterHash?: string;
+  /** @since 0.1.128 — hash of the canonical `@db.view.having` predicate. */
+  havingHash?: string;
+  materialized?: boolean;
+  /**
+   * @since 0.1.137 — the adapter's `viewRenderRevision()`, present only when
+   * the adapter defines one (managed views only).
+   */
+  renderRevision?: string;
+  fields: TFieldSnapshot[];
+}
+/**
+ * Extracts a canonical, serializable snapshot from a readable's metadata.
+ * Sorted deterministically so the hash is stable across runs.
+ *
+ * @param readable - The table/view readable.
+ * @param typeMapper - Optional adapter-specific type mapper. When provided,
+ *   each field's mapped type (e.g., "VARCHAR(255)") is stored in the snapshot
+ *   for precise type change detection.
+ */
+declare function computeTableSnapshot(readable: AtscriptDbReadable, typeMapper?: (field: TDbFieldMeta) => string, tableOptions?: TExistingTableOption[]): TTableSnapshot;
+/**
+ * Extracts a canonical, serializable snapshot from a view's metadata.
+ * Captures view plan (entry table, joins, filter, materialization) for
+ * detecting view definition changes.
+ */
+declare function computeViewSnapshot(view: AtscriptDbView): TViewSnapshot;
+/** Canonical (table-qualified, fixed-key-order) form of a view predicate. */
+type TCanonicalQueryNode = {
+  and: TCanonicalQueryNode[];
+} | {
+  or: TCanonicalQueryNode[];
+} | {
+  not: TCanonicalQueryNode;
+} /** `r` is `{ f: "<table>.<field>" }` for a field-to-field comparison, else the literal. */ | {
+  l: string;
+  op: string;
+  r?: unknown;
+};
+/**
+ * Converts a view predicate (join condition, `@db.view.filter`,
+ * `@db.view.having`) into a serializable structure whose JSON is a stable
+ * function of its MEANING: field refs become `qualify(ref)` — the view's
+ * `resolveFieldRef(ref, (n) => n)`, i.e. `"<table>.<field>"`, so a predicate
+ * retargeted to another table with the same field name changes — operators
+ * and literal values are kept as-is, `$and`/`$or` keep declaration order, and
+ * no function references survive. Two identical models produce byte-identical
+ * JSON.
+ * @since 0.1.128
+ */
+declare function canonicalizeQueryNode(node: AtscriptQueryNode, qualify: (ref: AtscriptQueryFieldRef) => string): TCanonicalQueryNode;
+/**
+ * Computes a deterministic hash string from multiple table snapshots.
+ * Uses FNV-1a for speed — not cryptographic, just needs stability + collision resistance.
+ */
+declare function computeSchemaHash(snapshots: Array<TTableSnapshot | TViewSnapshot>): string;
+/**
+ * Computes a hash for a single table/view snapshot.
+ * Used for per-table change detection via stored snapshots.
+ */
+declare function computeTableHash(snapshot: TTableSnapshot | TViewSnapshot): string;
+/**
+ * Converts stored snapshot fields to `TExistingColumn[]` format
+ * for use with `computeColumnDiff`. Used by adapters that lack
+ * native column introspection (e.g., MongoDB).
+ *
+ * The `type` field uses `mappedType` when available (adapter-specific),
+ * falling back to `designType`. Derived fields are left out (since 0.1.141):
+ * an adapter without column introspection stores no derived column, and a
+ * `physicalName` of one is its SOURCE path — reporting it as an existing
+ * column would have the diff drop the source leaf.
+ *
+ * With `readable`, the subfields of its navigation properties are left out
+ * too: a document adapter's snapshot lists them (for hash stability — see
+ * `snapshotFields`) although nothing is stored under a nav field — they are
+ * not columns to drop.
+ */
+declare function snapshotToExistingColumns(snapshot: TTableSnapshot, readable?: AtscriptDbReadable): TExistingColumn[];
+/**
+ * Extracts table options from a stored snapshot for diff comparison.
+ * Used as fallback when an adapter lacks native table option introspection.
+ */
+declare function snapshotToExistingTableOptions(snapshot: TTableSnapshot): TExistingTableOption[];
+//#endregion
+//#region src/schema/column-diff.d.ts
+/**
+ * Whether a live column's type differs from the type the adapter's
+ * `typeMapper` gives the field — the one rule schema sync diffs column types
+ * by (case-insensitive). Exported for adapters that must agree with it (the
+ * PostgreSQL recreate converts exactly the columns this reports changed).
+ * @since 0.1.137
+ */
+declare function isColumnTypeChanged(existingType: string, expectedType: string): boolean;
+/**
+ * Computes the difference between desired schema fields and existing database columns.
+ *
+ * @param desired - Field descriptors from the Atscript type (after flattening) —
+ *                  the readable's `columnDescriptors`; ignored descriptors are skipped.
+ * @param existing - Columns currently in the database (from introspection).
+ * @param typeMapper - Optional function to map field metadata to DB-native type strings.
+ *                     Receives the full field meta (design type, annotations, PK status, etc.)
+ *                     so adapters can produce context-aware types (e.g., `VARCHAR(255)` from maxLength).
+ *                     Required for type change detection.
+ * @param opts.snapshot - The table's stored snapshot (since 0.1.141) — the baseline a
+ *                        derived column's expression is compared with (the engine normalizes
+ *                        the expression it stores, so the live column cannot be). Without
+ *                        one, only a kind or type drift is seen.
+ */
+declare function computeColumnDiff(desired: readonly TDbFieldMeta[], existing: TExistingColumn[], typeMapper?: (field: TDbFieldMeta) => string, opts?: {
+  snapshot?: TTableSnapshot | null;
+}): TColumnDiff;
+//#endregion
+export { TTableSnapshot as a, TViewSnapshot as c, computeTableHash as d, computeTableSnapshot as f, snapshotToExistingTableOptions as h, TForeignKeySnapshot as i, canonicalizeQueryNode as l, snapshotToExistingColumns as m, isColumnTypeChanged as n, TViewColumnSnapshot as o, computeViewSnapshot as p, TFieldSnapshot as r, TViewJoinSnapshot as s, computeColumnDiff as t, computeSchemaHash as u };

package/dist/derived-rules-0sKn4f5C.mjs

@@ -0,0 +1,44 @@
+//#region src/shared/derived-rules.ts
+/**
+* The rules the compiler plugin and the runtime share about entities and
+* `@db.column.derived` fields — one dependency-free list each, so a
+* compile-time diagnostic and its runtime mirror can never disagree.
+* @since 0.1.141
+*/
+/** The annotations that make a declaration a DB entity: a table, or a managed / external view. */
+const DB_ENTITY_ANNOTATIONS = [
+	"db.table",
+	"db.view",
+	"db.view.for"
+];
+/** Primitive leaf types a JSON-stored path may end at (view JSON leaves, derived columns). */
+const JSON_LEAF_TYPES = new Set([
+	"string",
+	"number",
+	"boolean"
+]);
+/** Whether `type` (a resolved design type) is one of {@link JSON_LEAF_TYPES}. */
+function isJsonLeafType(type) {
+	return JSON_LEAF_TYPES.has(type);
+}
+/** Annotations a `@db.column.derived` field cannot carry (D8), with the reason. */
+const DERIVED_INCOMPATIBLE = [
+	["meta.id", "a computed column cannot identify the row"],
+	["db.rel.FK", "a foreign key needs a stored, writable column"],
+	["db.default", "the value is computed, never defaulted"],
+	["db.default.increment", "the value is computed, never defaulted"],
+	["db.default.uuid", "the value is computed, never defaulted"],
+	["db.default.now", "the value is computed, never defaulted"],
+	["db.column.version", "the version column is adapter-managed"],
+	["db.encrypted", "the value is a cleartext extraction of its source"],
+	["db.json", "a derived column is a primitive leaf, not a JSON value"],
+	["db.ignore", "an ignored field has no column to derive"],
+	["db.writeOnly", "a derived column is never written"],
+	["db.index.fulltext", "fulltext indexes need a stored text column"],
+	["db.index.geo", "a geo index needs a db.geoPoint column"],
+	["db.search.vector", "a vector index needs a stored embedding column"],
+	["db.mongo.search.text", "Atlas Search indexes the stored document, which holds no derived field"],
+	["db.mongo.search.autocomplete", "Atlas Search indexes the stored document, which holds no derived field"]
+];
+//#endregion
+export { isJsonLeafType as i, DERIVED_INCOMPATIBLE as n, JSON_LEAF_TYPES as r, DB_ENTITY_ANNOTATIONS as t };

package/dist/derived-rules-YstgIxG-.cjs

@@ -0,0 +1,67 @@
+//#region src/shared/derived-rules.ts
+/**
+* The rules the compiler plugin and the runtime share about entities and
+* `@db.column.derived` fields — one dependency-free list each, so a
+* compile-time diagnostic and its runtime mirror can never disagree.
+* @since 0.1.141
+*/
+/** The annotations that make a declaration a DB entity: a table, or a managed / external view. */
+const DB_ENTITY_ANNOTATIONS = [
+	"db.table",
+	"db.view",
+	"db.view.for"
+];
+/** Primitive leaf types a JSON-stored path may end at (view JSON leaves, derived columns). */
+const JSON_LEAF_TYPES = new Set([
+	"string",
+	"number",
+	"boolean"
+]);
+/** Whether `type` (a resolved design type) is one of {@link JSON_LEAF_TYPES}. */
+function isJsonLeafType(type) {
+	return JSON_LEAF_TYPES.has(type);
+}
+/** Annotations a `@db.column.derived` field cannot carry (D8), with the reason. */
+const DERIVED_INCOMPATIBLE = [
+	["meta.id", "a computed column cannot identify the row"],
+	["db.rel.FK", "a foreign key needs a stored, writable column"],
+	["db.default", "the value is computed, never defaulted"],
+	["db.default.increment", "the value is computed, never defaulted"],
+	["db.default.uuid", "the value is computed, never defaulted"],
+	["db.default.now", "the value is computed, never defaulted"],
+	["db.column.version", "the version column is adapter-managed"],
+	["db.encrypted", "the value is a cleartext extraction of its source"],
+	["db.json", "a derived column is a primitive leaf, not a JSON value"],
+	["db.ignore", "an ignored field has no column to derive"],
+	["db.writeOnly", "a derived column is never written"],
+	["db.index.fulltext", "fulltext indexes need a stored text column"],
+	["db.index.geo", "a geo index needs a db.geoPoint column"],
+	["db.search.vector", "a vector index needs a stored embedding column"],
+	["db.mongo.search.text", "Atlas Search indexes the stored document, which holds no derived field"],
+	["db.mongo.search.autocomplete", "Atlas Search indexes the stored document, which holds no derived field"]
+];
+//#endregion
+Object.defineProperty(exports, "DB_ENTITY_ANNOTATIONS", {
+	enumerable: true,
+	get: function() {
+		return DB_ENTITY_ANNOTATIONS;
+	}
+});
+Object.defineProperty(exports, "DERIVED_INCOMPATIBLE", {
+	enumerable: true,
+	get: function() {
+		return DERIVED_INCOMPATIBLE;
+	}
+});
+Object.defineProperty(exports, "JSON_LEAF_TYPES", {
+	enumerable: true,
+	get: function() {
+		return JSON_LEAF_TYPES;
+	}
+});
+Object.defineProperty(exports, "isJsonLeafType", {
+	enumerable: true,
+	get: function() {
+		return isJsonLeafType;
+	}
+});

package/dist/index.cjs

@@ -1,11 +1,13 @@
 Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
 const require_db_error = require("./db-error-DTkkeu5b.cjs");
-const require_column_diff = require("./column-diff-CgxgFKzx.cjs");
+const require_column_diff = require("./column-diff-CfPNcP6e.cjs");
 const require_aggregate_fns = require("./aggregate-fns-CGBv3E8S.cjs");
-const require_nested_writer = require("./nested-writer-BZNCuqI6.cjs");
-const require_validator = require("./validator-BtZbcLN2.cjs");
+const require_nested_writer = require("./nested-writer-DYsRxZ5f.cjs");
+const require_derived_rules = require("./derived-rules-YstgIxG-.cjs");
+const require_validator = require("./validator-DASnXf1j.cjs");
 const require_consts = require("./consts-BzRfCcH2.cjs");
 const require_ops = require("./ops.cjs");
+let _atscript_typescript_utils = require("@atscript/typescript/utils");
 let _uniqu_core = require("@uniqu/core");
 let node_crypto = require("node:crypto");
 //#region src/encryption.ts
@@ -203,6 +205,14 @@ async function withOptimisticRetry(table, filter, mutator, opts) {
 //#endregion
 //#region src/table/db-space.ts
 /**
+* A `@db.alias` type only names a join scope inside a view definition — it
+* is never a table or view of its own (since 0.1.141).
+*/
+function assertNotAlias(type) {
+	const target = require_column_diff.aliasTargetOf(type);
+	if (target) throw new Error(`"${type.id ?? ""}" is a @db.alias of "${target.id ?? ""}" — a join scope, not a table or view; register "${target.id ?? ""}" instead`);
+}
+/**
 * A database space — a registry of tables and views sharing the same adapter type and driver.
 *
 * `DbSpace` solves the cross-table discovery problem: when table A has a relation
@@ -259,6 +269,7 @@ var DbSpace = class {
 	getTable(type, logger) {
 		let readable = this._readables.get(type);
 		if (!readable) {
+			assertNotAlias(type);
 			readable = new require_column_diff.AtscriptDbTable(type, this._createAdapter(), logger || this.logger, (t) => this.get(t), (t) => {
 				const resolved = this.get(t);
 				return resolved instanceof require_column_diff.AtscriptDbTable ? resolved : void 0;
@@ -278,6 +289,7 @@ var DbSpace = class {
 	getView(type, logger) {
 		let readable = this._readables.get(type);
 		if (!readable) {
+			assertNotAlias(type);
 			readable = new require_column_diff.AtscriptDbView(type, this._createAdapter(), logger || this.logger, (t) => this.get(t));
 			readable.setEncryption(this._encryption);
 			this._readables.set(type, readable);
@@ -392,6 +404,24 @@ function translateQueryTree(node, resolveField) {
 	return { [leftField]: { [comp.op]: comp.right } };
 }
 //#endregion
+//#region src/table/db-entity.ts
+/**
+* Whether `value` is a compiled type a `DbSpace` accepts: an annotated type
+* whose own declaration carries `@db.table`, `@db.view` or `@db.view.for`.
+* A `@db.alias` type is not one, and neither is a plain `export type X = Table`
+* or a field typed with a table (`customer: Customer`) — since 0.1.141 the
+* entity annotations stay on the declaring interface instead of travelling
+* with every reference.
+*
+* Filters a module namespace before a sync:
+* `syncSchema(db, Object.values(models).filter(isDbEntityType))`.
+* @since 0.1.141
+*/
+function isDbEntityType(value) {
+	if (!(0, _atscript_typescript_utils.isAnnotatedType)(value)) return false;
+	return require_derived_rules.DB_ENTITY_ANNOTATIONS.some((name) => value.metadata.has(name));
+}
+//#endregion
 exports.$cas = require_ops.$cas;
 exports.$dec = require_ops.$dec;
 exports.$inc = require_ops.$inc;
@@ -425,6 +455,7 @@ exports.RelationalFieldMapper = require_column_diff.RelationalFieldMapper;
 exports.TableMetadata = require_column_diff.TableMetadata;
 exports.UniquSelect = require_column_diff.UniquSelect;
 exports.acceptedOperatorsHint = require_column_diff.acceptedOperatorsHint;
+exports.aliasTargetOf = require_column_diff.aliasTargetOf;
 exports.assertGeoPoint = require_column_diff.assertGeoPoint;
 exports.assertNoVersionWrites = require_column_diff.assertNoVersionWrites;
 exports.bucketSourceVerdict = require_column_diff.bucketSourceVerdict;
@@ -444,10 +475,12 @@ Object.defineProperty(exports, "computeInsights", {
 exports.createDbValidatorPlugin = require_validator.createDbValidatorPlugin;
 exports.createFailureCollector = require_column_diff.createFailureCollector;
 exports.decomposePatch = require_column_diff.decomposePatch;
-exports.findAncestorInSet = require_column_diff.findAncestorInSet;
+exports.deletePath = require_validator.deletePath;
+exports.findAncestorInSet = require_validator.findAncestorInSet;
 exports.forceNavNonOptional = require_validator.forceNavNonOptional;
 exports.getDbFieldOp = require_ops.getDbFieldOp;
 exports.getKeyProps = require_validator.getKeyProps;
+exports.getPath = require_validator.getPath;
 exports.guardAggregate = require_column_diff.guardAggregate;
 exports.guardFilter = require_column_diff.guardFilter;
 exports.guardPath = require_column_diff.guardPath;
@@ -456,6 +489,7 @@ exports.guardQuery = require_column_diff.guardQuery;
 exports.isAtscriptDbView = require_column_diff.isAtscriptDbView;
 exports.isBucketableField = require_column_diff.isBucketableField;
 exports.isColumnTypeChanged = require_column_diff.isColumnTypeChanged;
+exports.isDbEntityType = isDbEntityType;
 exports.isDbFieldOp = require_ops.isDbFieldOp;
 exports.isEmptyObject = require_validator.isEmptyObject;
 exports.isFieldRef = isFieldRef;