@fragno-dev/db 0.3.0 → 0.4.1

package/dist/browser/schema/create.js

@@ -0,0 +1,89 @@
+import "../id.js";
+import { generateId } from "./generate-id.js";
+
+//#region src/schema/create.ts
+/**
+* FragnoId represents a unified ID object that can contain external ID, internal ID, or both.
+* @internal
+*
+* For query inputs: externalId is sufficient (internalId is optional)
+* For query results: both externalId and internalId are provided
+*/
+var FragnoId = class FragnoId {
+	#externalId;
+	#internalId;
+	#version;
+	constructor({ externalId, internalId, version }) {
+		this.#externalId = externalId;
+		this.#internalId = internalId;
+		this.#version = version;
+	}
+	/**
+	* Create a FragnoId from just an external ID (for inputs)
+	*/
+	static fromExternal(externalId, version) {
+		return new FragnoId({
+			externalId,
+			version
+		});
+	}
+	get version() {
+		return this.#version;
+	}
+	get externalId() {
+		return this.#externalId;
+	}
+	get internalId() {
+		return this.#internalId;
+	}
+	/**
+	* Get the appropriate ID for database operations
+	* Prefers internal ID if available, falls back to external ID
+	*/
+	get databaseId() {
+		return this.#internalId ?? this.#externalId;
+	}
+	/**
+	* Convert to a plain object for serialization
+	*/
+	toJSON() {
+		return {
+			externalId: this.#externalId,
+			internalId: this.#internalId?.toString()
+		};
+	}
+	toString() {
+		return this.#externalId;
+	}
+	valueOf() {
+		return this.#externalId;
+	}
+};
+/**
+* FragnoReference represents a foreign key reference to another table's internal ID.
+* Unlike FragnoId, it only contains the internal ID (bigint) of the referenced record.
+* This is used for reference columns in query results.
+* @internal
+*/
+var FragnoReference = class FragnoReference {
+	#internalId;
+	constructor(internalId) {
+		this.#internalId = internalId;
+	}
+	/**
+	* Create a FragnoReference from an internal ID
+	*/
+	static fromInternal(internalId) {
+		return new FragnoReference(internalId);
+	}
+	/**
+	* Get the internal ID for database operations
+	*/
+	get internalId() {
+		return this.#internalId;
+	}
+};
+
+//#endregion
+export { FragnoId, FragnoReference };
+//# sourceMappingURL=create.js.map

package/dist/browser/schema/create.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"create.js","names":["#externalId","#internalId","#version"],"sources":["../../../src/schema/create.ts"],"sourcesContent":["import type { StandardSchemaV1 } from \"@standard-schema/spec\";\n\nimport { createId } from \"../id\";\nimport type { DbNow } from \"../query/db-now\";\nimport type { Prettify } from \"../util/types\";\nimport { createTableStandardSchemaProps, createTableValidator } from \"./validator\";\n\nexport { generateId } from \"./generate-id\";\nexport { FragnoDbValidationError } from \"./validator\";\n\nexport type AnySchema = Schema<Record<string, AnyTable>>;\n\nexport type AnyRelation = Relation;\n\nexport type AnyTable = Table;\n\nexport type AnyColumn =\n  | Column<keyof TypeMap, unknown, unknown>\n  | IdColumn<IdColumnType, unknown, unknown>\n  | InternalIdColumn<unknown, unknown>\n  | VersionColumn<unknown, unknown>;\n/**\n * Sub-operations that can be performed within table operations.\n * These are stored in order within add-table and alter-table operations.\n */\nexport type TableSubOperation =\n  | { type: \"add-column\"; columnName: string; column: AnyColumn }\n  | { type: \"add-index\"; name: string; columns: string[]; unique: boolean }\n  | { type: \"rename-column\"; from: string; to: string }\n  | { type: \"drop-column\"; name: string }\n  | {\n      type: \"update-column\";\n      columnName: string;\n      column: AnyColumn;\n      updateNullable: boolean;\n      updateDefault: boolean;\n      updateDataType: boolean;\n    }\n  | {\n      type: \"add-foreign-key\";\n      name: string;\n      columns: string[];\n      referencedTable: string;\n      referencedColumns: string[];\n    };\n\n/**\n * Operations that can be performed on a schema during its definition.\n * These are tracked so we can generate migrations for specific version ranges.\n */\nexport type SchemaOperation =\n  | {\n      type: \"add-table\";\n      tableName: string;\n      operations: TableSubOperation[]; // Ordered list of sub-operations\n    }\n  | {\n      type: \"alter-table\";\n      tableName: string;\n      operations: TableSubOperation[]; // Ordered list of sub-operations\n    }\n  | {\n      type: \"add-reference\";\n      tableName: string; // The table that has the foreign key\n      referenceName: string;\n      config: {\n        type: \"one\" | \"many\";\n        from: { table: string; column: string };\n        to: { table: string; column: string };\n        foreignKey?: boolean;\n      };\n    };\n\nexport interface ForeignKey {\n  name: string;\n  table: AnyTable;\n  columns: AnyColumn[];\n\n  referencedTable: AnyTable;\n  referencedColumns: AnyColumn[];\n}\n\nclass RelationInit<\n  TRelationType extends RelationType,\n  TTables extends Record<string, AnyTable>,\n  TTableName extends keyof TTables,\n> {\n  type: TRelationType;\n  referencedTable: TTables[TTableName];\n  referencer: AnyTable;\n  on: [string, string][] = [];\n  foreignKey: boolean;\n\n  constructor(\n    type: TRelationType,\n    referencedTable: TTables[TTableName],\n    referencer: AnyTable,\n    options?: { foreignKey?: boolean },\n  ) {\n    this.type = type;\n    this.referencedTable = referencedTable;\n    this.referencer = referencer;\n    this.foreignKey = options?.foreignKey ?? true;\n  }\n}\n\nexport interface Index<\n  TColumns extends AnyColumn[] = AnyColumn[],\n  TColumnNames extends readonly string[] = readonly string[],\n> {\n  name: string;\n  columns: TColumns;\n  columnNames: TColumnNames;\n  unique: boolean;\n}\n\nexport class ExplicitRelationInit<\n  TRelationType extends RelationType,\n  TTables extends Record<string, AnyTable>,\n  TTableName extends keyof TTables,\n> extends RelationInit<TRelationType, TTables, TTableName> {\n  init(name: string): Relation<TRelationType, TTables[TTableName]> {\n    const id = `${this.referencer.name}_${this.referencedTable.name}`;\n\n    return {\n      id,\n      on: this.on,\n      name,\n      referencer: this.referencer,\n      table: this.referencedTable,\n      type: this.type,\n      foreignKey: this.foreignKey,\n    };\n  }\n}\n\nexport interface Relation<\n  TRelationType extends RelationType = RelationType,\n  TTable extends AnyTable = AnyTable,\n> {\n  id: string;\n  name: string;\n  type: TRelationType;\n  foreignKey?: boolean;\n\n  table: TTable;\n  referencer: AnyTable;\n\n  on: [string, string][];\n}\n\ntype PickNullable<T> = {\n  [P in keyof T as null extends T[P] ? P : never]: T[P];\n};\n\ntype PickNotNullable<T> = {\n  [P in keyof T as null extends T[P] ? never : P]: T[P];\n};\n\ntype RawInsertValuesFromColumns<TColumns extends Record<string, AnyColumn>> = {\n  [K in keyof TColumns as string extends K ? never : K]: TColumns[K][\"$in\"];\n};\n\ntype TableInsertValuesFromColumns<TColumns extends Record<string, AnyColumn>> = Prettify<\n  Partial<PickNullable<RawInsertValuesFromColumns<TColumns>>> &\n    PickNotNullable<RawInsertValuesFromColumns<TColumns>>\n>;\n\nexport type TableInsertValues<T extends AnyTable> = TableInsertValuesFromColumns<T[\"columns\"]>;\n\nexport type TableUnknownKeysMode = \"strip\" | \"strict\";\n\nexport type TableValidationOptions = {\n  unknownKeys?: TableUnknownKeysMode;\n};\n\nexport interface Table<\n  TColumns extends Record<string, AnyColumn> = Record<string, AnyColumn>,\n  TRelations extends Record<string, AnyRelation> = Record<string, AnyRelation>,\n  TIndexes extends Record<string, Index> = Record<string, Index>,\n> {\n  /**\n   * Standard Schema-compatible validator for insert values.\n   */\n  \"~standard\": StandardSchemaV1.Props<\n    TableInsertValuesFromColumns<TColumns>,\n    TableInsertValuesFromColumns<TColumns>\n  >;\n  name: string;\n\n  columns: TColumns;\n  relations: TRelations;\n  indexes: TIndexes;\n\n  /**\n   * Validate insert values at runtime.\n   */\n  validate: (\n    value: unknown,\n    options?: TableValidationOptions,\n  ) => TableInsertValuesFromColumns<TColumns>;\n\n  /**\n   * Get column by name\n   */\n  getColumnByName: (name: string) => AnyColumn | undefined;\n  /**\n   * Get the external ID column (user-facing)\n   */\n  getIdColumn: () => AnyColumn;\n  /**\n   * Get the internal ID column (database-native, used for joins)\n   */\n  getInternalIdColumn: () => AnyColumn;\n  /**\n   * Get the version column (for optimistic concurrency control)\n   */\n  getVersionColumn: () => AnyColumn;\n}\n\ntype DBSpecial = { tag: \"special\"; value: \"now\" };\ntype RuntimeSpecial = { tag: \"special\"; value: \"cuid\" | \"now\" };\n\n/**\n * Builder for database-level default values.\n */\nexport interface DefaultBuilder {\n  /** Database-generated timestamp (DEFAULT NOW()) */\n  now(): DBSpecial;\n}\n\n/**\n * Builder for runtime-generated default values.\n */\nexport interface RuntimeDefaultBuilder {\n  /** Generate CUID identifier */\n  cuid(): RuntimeSpecial;\n  /** Generate current timestamp */\n  now(): RuntimeSpecial;\n}\n\nconst defaultBuilder: DefaultBuilder = {\n  now: () => ({ tag: \"special\", value: \"now\" }),\n};\n\nconst runtimeDefaultBuilder: RuntimeDefaultBuilder = {\n  cuid: () => ({ tag: \"special\", value: \"cuid\" }),\n  now: () => ({ tag: \"special\", value: \"now\" }),\n};\n\ntype IdColumnType = `varchar(${number})`;\n\nexport type TypeMap = {\n  string: string;\n  bigint: bigint;\n  integer: number;\n  decimal: number;\n  bool: boolean;\n  json: unknown;\n  /**\n   * this follows the same specs as Prisma `Bytes` for consistency.\n   */\n  binary: Uint8Array;\n  date: Date;\n  timestamp: Date;\n} & Record<`varchar(${number})`, string>;\n\nexport class Column<TType extends keyof TypeMap, TIn = unknown, TOut = unknown> {\n  type: TType;\n  name: string = \"\";\n  isNullable: boolean = false;\n  role: \"external-id\" | \"internal-id\" | \"version\" | \"reference\" | \"regular\" = \"regular\";\n  isHidden: boolean = false;\n\n  default?:\n    | { value: TypeMap[TType] }\n    | { dbSpecial: \"now\" }\n    | { runtime: \"cuid\" | \"now\" | (() => TypeMap[TType]) };\n\n  tableName: string = \"\";\n\n  constructor(type: TType) {\n    this.type = type;\n  }\n\n  nullable<TNullable extends boolean = true>(nullable?: TNullable) {\n    this.isNullable = nullable ?? true;\n\n    return this as Column<\n      TType,\n      TNullable extends true ? TIn | null : Exclude<TIn, null>,\n      TNullable extends true ? TOut | null : Exclude<TOut, null>\n    >;\n  }\n\n  hidden<THidden extends boolean = true>(hidden?: THidden) {\n    this.isHidden = hidden ?? true;\n    return this as Column<TType, null, null>;\n  }\n\n  /**\n   * Generate default value at runtime in application code (not in the database).\n   *\n   * Use this when you need values generated in your application code, either because:\n   * - Your database doesn't support the operation (e.g., generating CUIDs)\n   * - You want consistent behavior across all databases\n   * - You need custom generation logic\n   *\n   * @param value - Either a literal value or builder callback:\n   *   - Literal: Any static value of the column type\n   *   - `(b) => b.cuid()` - Generate a CUID identifier\n   *   - `(b) => b.now()` - Generate current timestamp\n   *   - `(b) => ...` - Custom function that returns the default value\n   *\n   * @example\n   * ```ts\n   * column(\"string\").defaultTo$((b) => b.cuid())           // Generate CUID at runtime\n   * column(\"timestamp\").defaultTo$((b) => b.now())         // Generate timestamp at runtime\n   * column(\"integer\").defaultTo$(42)                       // Static literal\n   * column(\"integer\").defaultTo$((b) => Math.floor(Math.random() * 100))  // Custom function\n   * ```\n   */\n  defaultTo$(\n    value: TypeMap[TType] | ((builder: RuntimeDefaultBuilder) => RuntimeSpecial | TypeMap[TType]),\n  ): Column<TType, TIn | null, TOut> {\n    if (typeof value === \"function\") {\n      const fn = value as (builder: RuntimeDefaultBuilder) => RuntimeSpecial | TypeMap[TType];\n      const result = fn(runtimeDefaultBuilder);\n      if (\n        typeof result === \"object\" &&\n        result !== null &&\n        \"tag\" in result &&\n        result.tag === \"special\"\n      ) {\n        this.default = { runtime: result.value };\n      } else {\n        // Custom function - we need to wrap the callback to call it again later\n        this.default = { runtime: () => fn(runtimeDefaultBuilder) as TypeMap[TType] };\n      }\n    } else {\n      // Direct literal value - wrap it in a function for runtime generation\n      this.default = { runtime: () => value };\n    }\n    return this;\n  }\n\n  /**\n   * Set a database-level default value (generated by the database, not application code).\n   *\n   * The database will generate the default value when inserting rows. If the database\n   * doesn't support the operation, Fragno will fall back to generating the value in\n   * application code.\n   *\n   * @param value - Either a literal value or builder callback:\n   *   - Literal: Any static value of the column type\n   *   - `(b) => b.now()` - Database-generated timestamp\n   *\n   * @example\n   * ```ts\n   * // Static defaults\n   * column(\"string\").defaultTo(\"active\")\n   * column(\"integer\").defaultTo(0)\n   * column(\"boolean\").defaultTo(true)\n   *\n   * // Database-generated timestamp (with fallback)\n   * column(\"timestamp\").defaultTo((b) => b.now())\n   * ```\n   */\n  defaultTo(\n    value: TypeMap[TType] | ((builder: DefaultBuilder) => DBSpecial | TypeMap[TType]),\n  ): Column<TType, TIn | null, TOut> {\n    if (typeof value === \"function\") {\n      const fn = value as (builder: DefaultBuilder) => DBSpecial | TypeMap[TType];\n      const result = fn(defaultBuilder);\n      if (\n        typeof result === \"object\" &&\n        result !== null &&\n        \"tag\" in result &&\n        result.tag === \"special\"\n      ) {\n        this.default = { dbSpecial: result.value };\n      } else {\n        this.default = { value: result as TypeMap[TType] };\n      }\n    } else {\n      this.default = { value };\n    }\n    return this;\n  }\n\n  /**\n   * Generate default value for the column at runtime.\n   * Used for both runtime defaults (defaultTo$) and fallback generation for\n   * database defaults (defaultTo) when the database doesn't support them.\n   */\n  generateDefaultValue(): TypeMap[TType] | undefined {\n    if (!this.default) {\n      return;\n    }\n\n    if (\"value\" in this.default) {\n      return this.default.value;\n    }\n\n    if (\"dbSpecial\" in this.default) {\n      // Fallback generation for database-level special functions\n      if (this.default.dbSpecial === \"now\") {\n        return new Date(Date.now()) as TypeMap[TType];\n      }\n      return;\n    }\n\n    // Runtime defaults (defaultTo$)\n    if (this.default.runtime === \"cuid\") {\n      return createId() as TypeMap[TType];\n    }\n    if (this.default.runtime === \"now\") {\n      return new Date(Date.now()) as TypeMap[TType];\n    }\n\n    // Custom function\n    return this.default.runtime();\n  }\n\n  /**\n   * @description This is used for type inference only. Runtime value will be undefined.\n   * @internal\n   */\n  get $in(): TIn {\n    return undefined as unknown as TIn;\n  }\n\n  /**\n   * @description This is used for type inference only. Runtime value will be undefined.\n   * @internal\n   */\n  get $out(): TOut {\n    return undefined as unknown as TOut;\n  }\n}\n\nexport class IdColumn<\n  TType extends IdColumnType = IdColumnType,\n  TIn = unknown,\n  TOut = unknown,\n> extends Column<TType, TIn, TOut> {\n  id = true;\n\n  override defaultTo$(\n    value: TypeMap[TType] | ((builder: RuntimeDefaultBuilder) => RuntimeSpecial | TypeMap[TType]),\n  ) {\n    return super.defaultTo$(value) as IdColumn<TType, TIn | null, TOut>;\n  }\n\n  override defaultTo(\n    value: TypeMap[TType] | ((builder: DefaultBuilder) => DBSpecial | TypeMap[TType]),\n  ) {\n    return super.defaultTo(value) as IdColumn<TType, TIn | null, TOut>;\n  }\n}\n\n/**\n * Internal ID column - used for database-native joins and foreign keys.\n * Hidden from user API by default.\n */\nexport class InternalIdColumn<TIn = unknown, TOut = unknown> extends Column<\"bigint\", TIn, TOut> {\n  override role = \"internal-id\" as const;\n\n  constructor() {\n    super(\"bigint\");\n    this.hidden();\n  }\n}\n\n/**\n * Version column - used for optimistic concurrency control.\n * Automatically incremented on each update.\n */\nexport class VersionColumn<TIn = unknown, TOut = unknown> extends Column<\"integer\", TIn, TOut> {\n  override role = \"version\" as const;\n\n  constructor() {\n    super(\"integer\");\n    this.defaultTo(0).hidden();\n  }\n}\n\nfunction cloneColumn<TColumn extends AnyColumn>(col: TColumn): TColumn {\n  let clonedCol: AnyColumn;\n\n  if (col instanceof InternalIdColumn) {\n    clonedCol = new InternalIdColumn();\n  } else if (col instanceof VersionColumn) {\n    clonedCol = new VersionColumn();\n  } else if (col instanceof IdColumn) {\n    clonedCol = new IdColumn(col.type);\n  } else {\n    clonedCol = new Column(col.type);\n  }\n\n  clonedCol.name = col.name;\n  clonedCol.isNullable = col.isNullable;\n  clonedCol.role = col.role;\n  clonedCol.isHidden = col.isHidden;\n  clonedCol.default = col.default;\n  clonedCol.tableName = col.tableName;\n\n  return clonedCol as TColumn;\n}\n\ntype ColumnInput<TType extends keyof TypeMap> =\n  | TypeMap[TType]\n  | (TType extends \"timestamp\" | \"date\" ? DbNow : never);\n\nexport function column<TType extends keyof TypeMap>(\n  type: TType,\n): Column<TType, ColumnInput<TType>, TypeMap[TType]> {\n  return new Column(type);\n}\n\n/**\n * Create a reference column that points to another table's internal ID.\n * This is used for foreign key relationships.\n * Always uses bigint to match the internal ID type.\n */\nexport function referenceColumn(): Column<\n  \"bigint\",\n  string | bigint | FragnoId | FragnoReference,\n  FragnoReference\n> {\n  const col = new Column<\"bigint\", string | bigint | FragnoId | FragnoReference, FragnoReference>(\n    \"bigint\",\n  );\n  col.role = \"reference\";\n  return col;\n}\n\n/**\n * Create an external ID column (user-facing).\n * This is a CUID string that can be auto-generated or user-provided.\n * Input accepts string | FragnoId | null, output returns FragnoId.\n */\nexport function idColumn(): IdColumn<\"varchar(128)\", string | FragnoId | null, FragnoId> {\n  const col = new IdColumn<\"varchar(128)\", string | FragnoId | null, FragnoId>(\"varchar(128)\");\n  col.role = \"external-id\";\n  col.defaultTo$((b) => b.cuid());\n  return col;\n}\n\n/**\n * Create an internal ID column (database-native, hidden from user API).\n * Used for joins and foreign keys.\n * @internal\n */\nexport function internalIdColumn(): InternalIdColumn<null, bigint> {\n  const col = new InternalIdColumn<null, bigint>();\n  col.role = \"internal-id\";\n  col.hidden();\n  return col;\n}\n\n/**\n * Create a version column for optimistic concurrency control.\n * @internal\n */\nexport function versionColumn(): VersionColumn<null, number> {\n  const col = new VersionColumn<null, number>();\n  col.role = \"version\";\n  col.hidden();\n  return col;\n}\n\n/**\n * FragnoId represents a unified ID object that can contain external ID, internal ID, or both.\n * @internal\n *\n * For query inputs: externalId is sufficient (internalId is optional)\n * For query results: both externalId and internalId are provided\n */\nexport class FragnoId {\n  readonly #externalId: string;\n  readonly #internalId?: bigint;\n  readonly #version: number;\n\n  constructor({\n    externalId,\n    internalId,\n    version,\n  }: {\n    externalId: string;\n    internalId?: bigint;\n    version: number;\n  }) {\n    this.#externalId = externalId;\n    this.#internalId = internalId;\n    this.#version = version;\n  }\n\n  /**\n   * Create a FragnoId from just an external ID (for inputs)\n   */\n  static fromExternal(externalId: string, version: number): FragnoId {\n    return new FragnoId({ externalId, version });\n  }\n\n  get version(): number {\n    return this.#version;\n  }\n\n  get externalId(): string {\n    return this.#externalId;\n  }\n\n  get internalId(): bigint | undefined {\n    return this.#internalId;\n  }\n\n  /**\n   * Get the appropriate ID for database operations\n   * Prefers internal ID if available, falls back to external ID\n   */\n  get databaseId(): string | bigint {\n    return this.#internalId ?? this.#externalId;\n  }\n\n  /**\n   * Convert to a plain object for serialization\n   */\n  toJSON(): { externalId: string; internalId?: string } {\n    return {\n      externalId: this.#externalId,\n      internalId: this.#internalId?.toString(),\n    };\n  }\n\n  toString(): string {\n    return this.#externalId;\n  }\n\n  valueOf(): string {\n    return this.#externalId;\n  }\n}\n\n/**\n * FragnoReference represents a foreign key reference to another table's internal ID.\n * Unlike FragnoId, it only contains the internal ID (bigint) of the referenced record.\n * This is used for reference columns in query results.\n * @internal\n */\nexport class FragnoReference {\n  readonly #internalId: bigint;\n\n  constructor(internalId: bigint) {\n    this.#internalId = internalId;\n  }\n\n  /**\n   * Create a FragnoReference from an internal ID\n   */\n  static fromInternal(internalId: bigint): FragnoReference {\n    return new FragnoReference(internalId);\n  }\n\n  /**\n   * Get the internal ID for database operations\n   */\n  get internalId(): bigint {\n    return this.#internalId;\n  }\n}\n\nconst validationClasses = { FragnoId, FragnoReference };\n\ntype RelationType = \"one\" | \"many\";\n\nexport class TableBuilder<\n  TColumns extends Record<string, AnyColumn> = Record<string, AnyColumn>,\n  TRelations extends Record<string, AnyRelation> = Record<string, AnyRelation>,\n  TIndexes extends Record<string, Index> = Record<string, Index>,\n> {\n  #name: string;\n  #columns: TColumns;\n  #relations: TRelations;\n  #indexes: TIndexes;\n  #columnOrder: string[] = [];\n\n  constructor(name: string) {\n    this.#name = name;\n    this.#columns = {} as TColumns;\n    this.#relations = {} as TRelations;\n    this.#indexes = {} as TIndexes;\n  }\n\n  // For alterTable to set existing state\n  setColumns(columns: TColumns): void {\n    this.#columns = { ...columns };\n  }\n\n  setRelations(relations: TRelations): void {\n    this.#relations = { ...relations };\n  }\n\n  setIndexes(indexes: TIndexes): void {\n    this.#indexes = { ...indexes };\n  }\n\n  // For SchemaBuilder to read collected indexes\n  getIndexes(): Index[] {\n    return Object.values(this.#indexes) as Index[];\n  }\n\n  getColumnOrder(): string[] {\n    return this.#columnOrder;\n  }\n\n  /**\n   * Add a column to the table.\n   */\n  addColumn<TColumnName extends string, TColumn extends AnyColumn>(\n    name: TColumnName,\n    col: TColumn,\n  ): TableBuilder<TColumns & Record<TColumnName, TColumn>, TRelations, TIndexes>;\n\n  /**\n   * Add a column to the table with simplified syntax.\n   */\n  addColumn<TColumnName extends string, TType extends keyof TypeMap>(\n    name: TColumnName,\n    type: TType,\n  ): TableBuilder<\n    TColumns & Record<TColumnName, Column<TType, ColumnInput<TType>, TypeMap[TType]>>,\n    TRelations,\n    TIndexes\n  >;\n\n  addColumn<TColumnName extends string, TColumn extends AnyColumn, TType extends keyof TypeMap>(\n    name: TColumnName,\n    colOrType: TColumn | TType,\n  ): TableBuilder<TColumns & Record<TColumnName, TColumn>, TRelations, TIndexes> {\n    // Create the column if a type string was provided\n    const col = typeof colOrType === \"string\" ? column(colOrType) : colOrType;\n\n    // Set column metadata\n    col.name = name;\n\n    // Add column directly to this builder\n    this.#columns[name] = col as unknown as TColumns[TColumnName];\n    this.#columnOrder.push(name);\n\n    return this as unknown as TableBuilder<\n      TColumns & Record<TColumnName, TColumn>,\n      TRelations,\n      TIndexes\n    >;\n  }\n\n  /**\n   * Alter an existing column.\n   */\n  alterColumn<TColumnName extends NonIdColumnName<TColumns>>(\n    name: TColumnName,\n  ): ColumnAlterer<TColumns, TRelations, TIndexes, TColumnName> {\n    return {\n      nullable: <TNullable extends boolean = true>(nullable?: TNullable) => {\n        const column = this.#columns[name];\n        if (!column) {\n          throw new Error(`Unknown column name ${String(name)}`);\n        }\n\n        const cloned = cloneColumn(column) as Column<keyof TypeMap>;\n        const updated = cloned.nullable(nullable ?? true);\n        this.#columns[name] = updated as unknown as TColumns[TColumnName];\n\n        return this as unknown as TableBuilder<\n          UpdateColumn<TColumns, TColumnName, NullableColumn<TColumns[TColumnName], TNullable>>,\n          TRelations,\n          TIndexes\n        >;\n      },\n    };\n  }\n\n  /**\n   * Create an index on the specified columns.\n   */\n  createIndex<\n    TIndexName extends string,\n    const TColumnNames extends readonly (string & keyof TColumns)[],\n  >(\n    name: TIndexName,\n    columns: TColumnNames,\n    options?: { unique?: boolean },\n  ): TableBuilder<\n    TColumns,\n    TRelations,\n    TIndexes & Record<TIndexName, Index<ColumnsToTuple<TColumns, TColumnNames>, TColumnNames>>\n  > {\n    const cols = columns.map((colName) => {\n      const column = this.#columns[colName];\n      if (!column) {\n        throw new Error(`Unknown column name ${colName}`);\n      }\n      return column;\n    });\n\n    const unique = options?.unique ?? false;\n    // Safe: we're adding the index to the internal indexes object\n    this.#indexes[name] = {\n      name,\n      columns: cols,\n      columnNames: columns,\n      unique,\n    } as unknown as TIndexes[TIndexName];\n\n    return this as unknown as TableBuilder<\n      TColumns,\n      TRelations,\n      TIndexes & Record<TIndexName, Index<ColumnsToTuple<TColumns, TColumnNames>, TColumnNames>>\n    >;\n  }\n\n  /**\n   * Build the final table. This should be called after all columns are added.\n   */\n  build(): Table<TColumns, TRelations, TIndexes> {\n    let idCol: AnyColumn | undefined;\n    let internalIdCol: AnyColumn | undefined;\n    let versionCol: AnyColumn | undefined;\n\n    // TODO: Throw if user manually added version/internalId columns\n\n    // Auto-add _internalId and _version columns if not already present\n    if (!this.#columns[\"_internalId\"]) {\n      const col = internalIdColumn();\n      col.name = \"_internalId\";\n      // Safe: we're adding system columns to the internal columns object\n      (this.#columns as Record<string, AnyColumn>)[\"_internalId\"] = col;\n    }\n\n    if (!this.#columns[\"_version\"]) {\n      const col = versionColumn();\n      col.name = \"_version\";\n      // Safe: we're adding system columns to the internal columns object\n      (this.#columns as Record<string, AnyColumn>)[\"_version\"] = col;\n    }\n\n    const table = {\n      name: this.#name,\n      columns: this.#columns,\n      relations: this.#relations,\n      indexes: this.#indexes,\n      getColumnByName: (name) => {\n        return Object.values(this.#columns).find((c) => c.name === name);\n      },\n      getIdColumn: () => {\n        return idCol!;\n      },\n      getInternalIdColumn: () => {\n        return internalIdCol!;\n      },\n      getVersionColumn: () => {\n        return versionCol!;\n      },\n    } as Table<TColumns, TRelations, TIndexes>;\n\n    table[\"~standard\"] = createTableStandardSchemaProps(table, validationClasses);\n    table.validate = createTableValidator(table, validationClasses);\n\n    // Set table reference and find special columns\n    for (const k in this.#columns) {\n      const column = this.#columns[k];\n      if (!column) {\n        continue;\n      }\n\n      column.tableName = table.name;\n      if (column instanceof IdColumn || column.role === \"external-id\") {\n        idCol = column;\n      }\n      if (column instanceof InternalIdColumn || column.role === \"internal-id\") {\n        internalIdCol = column;\n      }\n      if (column instanceof VersionColumn || column.role === \"version\") {\n        versionCol = column;\n      }\n    }\n\n    if (idCol === undefined) {\n      throw new Error(`there's no id column in your table ${this.#name}`);\n    }\n    if (internalIdCol === undefined) {\n      throw new Error(`there's no internal id column in your table ${this.#name}`);\n    }\n    if (versionCol === undefined) {\n      throw new Error(`there's no version column in your table ${this.#name}`);\n    }\n\n    return table;\n  }\n}\n\nexport interface Schema<TTables extends Record<string, AnyTable> = Record<string, AnyTable>> {\n  /**\n   * @description The name of the schema (required).\n   */\n  name: string;\n  /**\n   * @description The version of the schema, automatically incremented on each change.\n   */\n  version: number;\n  tables: TTables;\n  /**\n   * @description Operations performed on this schema, in order.\n   * Used to generate migrations for specific version ranges.\n   */\n  operations: SchemaOperation[];\n\n  clone: () => Schema<TTables>;\n}\n\n/**\n * Utility type for updating a single table's relations in a schema.\n * Used to properly type the return value of addReference.\n */\ntype UpdateTableRelations<\n  TTables extends Record<string, AnyTable>,\n  TTableName extends keyof TTables,\n  TReferenceName extends string,\n  TReferencedTableName extends keyof TTables,\n  TRelationType extends RelationType = RelationType,\n> = {\n  [K in keyof TTables]: K extends TTableName\n    ? Table<\n        TTables[TTableName][\"columns\"],\n        TTables[TTableName][\"relations\"] &\n          Record<TReferenceName, Relation<TRelationType, TTables[TReferencedTableName]>>,\n        TTables[TTableName][\"indexes\"]\n      >\n    : TTables[K];\n};\n\n/**\n * Utility type for updating a single table in a schema.\n * Used to properly type the return value of alterTable.\n */\ntype UpdateTable<\n  TTables extends Record<string, AnyTable>,\n  TTableName extends keyof TTables,\n  TNewColumns extends Record<string, AnyColumn>,\n  TNewRelations extends Record<string, AnyRelation>,\n  TNewIndexes extends Record<string, Index>,\n> = {\n  [K in keyof TTables]: K extends TTableName\n    ? Table<TNewColumns, TNewRelations, TNewIndexes>\n    : TTables[K];\n};\n\n/**\n * Map an array of column names to a tuple of their actual column types\n */\ntype ColumnsToTuple<\n  TColumns extends Record<string, AnyColumn>,\n  TColumnNames extends readonly (keyof TColumns)[],\n> = {\n  [K in keyof TColumnNames]: TColumnNames[K] extends keyof TColumns\n    ? TColumns[TColumnNames[K]]\n    : never;\n} & AnyColumn[];\n\ntype UpdateColumn<\n  TColumns extends Record<string, AnyColumn>,\n  TColumnName extends keyof TColumns,\n  TUpdatedColumn extends AnyColumn,\n> = Prettify<Omit<TColumns, TColumnName> & Record<TColumnName, TUpdatedColumn>>;\n\ntype NonIdColumnName<TColumns extends Record<string, AnyColumn>> = {\n  [K in keyof TColumns]: TColumns[K] extends\n    | IdColumn<IdColumnType, unknown, unknown>\n    | InternalIdColumn<unknown, unknown>\n    | VersionColumn<unknown, unknown>\n    ? never\n    : K;\n}[keyof TColumns];\n\ntype NullableColumn<TColumn extends AnyColumn, TNullable extends boolean> =\n  TColumn extends Column<infer TType, infer TIn, infer TOut>\n    ? Column<\n        TType,\n        TNullable extends true ? TIn | null : Exclude<TIn, null>,\n        TNullable extends true ? TOut | null : Exclude<TOut, null>\n      >\n    : TColumn;\n\ntype ColumnAlterer<\n  TColumns extends Record<string, AnyColumn>,\n  TRelations extends Record<string, AnyRelation>,\n  TIndexes extends Record<string, Index>,\n  TColumnName extends keyof TColumns,\n> = {\n  nullable<TNullable extends boolean = true>(\n    nullable?: TNullable,\n  ): TableBuilder<\n    UpdateColumn<TColumns, TColumnName, NullableColumn<TColumns[TColumnName], TNullable>>,\n    TRelations,\n    TIndexes\n  >;\n};\n\nexport class SchemaBuilder<TTables extends Record<string, AnyTable> = {}> {\n  #name: string;\n  #tables: TTables;\n  #version: number = 0;\n  #operations: SchemaOperation[] = [];\n  #tableNames: Set<string> = new Set();\n  #indexNames: Set<string> = new Set();\n\n  constructor(name: string, existingSchema?: Schema<TTables>) {\n    this.#name = name;\n    if (existingSchema) {\n      this.#tables = existingSchema.tables;\n      this.#version = existingSchema.version;\n      this.#operations = [...existingSchema.operations];\n    } else {\n      this.#tables = {} as TTables;\n    }\n\n    for (const table of Object.values(this.#tables)) {\n      this.#registerTableName(table.name);\n      for (const index of Object.values(table.indexes)) {\n        this.#registerIndexName(index.name, table.name);\n      }\n    }\n  }\n\n  #registerTableName(name: string): void {\n    if (this.#tableNames.has(name)) {\n      throw new Error(`Duplicate table name \"${name}\" in schema \"${this.#name}\".`);\n    }\n    this.#tableNames.add(name);\n  }\n\n  #registerIndexName(name: string, tableName: string): void {\n    if (this.#indexNames.has(name)) {\n      throw new Error(\n        `Duplicate index name \"${name}\" in schema \"${this.#name}\". Index names must be unique across tables (conflict on \"${tableName}\").`,\n      );\n    }\n    this.#indexNames.add(name);\n  }\n\n  #rebindRelations(tableName: string, newTable: AnyTable): void {\n    for (const table of Object.values(this.#tables)) {\n      for (const relation of Object.values(table.relations)) {\n        if (relation.table.name === tableName) {\n          relation.table = newTable;\n        }\n        if (relation.referencer.name === tableName) {\n          relation.referencer = newTable;\n        }\n      }\n    }\n  }\n\n  #isJoinColumnIndexed(table: AnyTable, columnName: string): boolean {\n    const idColumnName = table.getIdColumn().name;\n    const internalIdColumnName = table.getInternalIdColumn().name;\n    if (columnName === idColumnName || columnName === internalIdColumnName) {\n      return true;\n    }\n\n    return Object.values(table.indexes).some((index) =>\n      index.columnNames.some((name) => name === columnName),\n    );\n  }\n\n  /**\n   * Add an existing schema to this builder.\n   * Merges tables and operations from the provided schema.\n   *\n   * @example\n   * ```ts\n   * const builder = new SchemaBuilder(\"combined\")\n   *   .add(userSchema)\n   *   .add(postSchema)\n   *   .addTable(\"comments\", ...);\n   * ```\n   */\n  mergeWithExistingSchema<TNewTables extends Record<string, AnyTable>>(\n    schema: Schema<TNewTables>,\n  ): SchemaBuilder<TTables & TNewTables> {\n    for (const table of Object.values(schema.tables)) {\n      if (this.#tableNames.has(table.name)) {\n        throw new Error(\n          `Duplicate table name \"${table.name}\" in schema \"${this.#name}\" when merging.`,\n        );\n      }\n      for (const index of Object.values(table.indexes)) {\n        if (this.#indexNames.has(index.name)) {\n          throw new Error(\n            `Duplicate index name \"${index.name}\" in schema \"${this.#name}\" when merging (conflict on \"${table.name}\").`,\n          );\n        }\n      }\n    }\n\n    this.#tables = { ...this.#tables, ...schema.tables } as TTables & TNewTables;\n    this.#operations = [...this.#operations, ...schema.operations];\n    this.#version += schema.version;\n\n    for (const table of Object.values(schema.tables)) {\n      this.#tableNames.add(table.name);\n      for (const index of Object.values(table.indexes)) {\n        this.#indexNames.add(index.name);\n      }\n    }\n\n    return this as unknown as SchemaBuilder<TTables & TNewTables>;\n  }\n\n  /**\n   * Add a table to the schema. Increments the version counter.\n   */\n  addTable<\n    TTableName extends string,\n    TColumns extends Record<string, AnyColumn>,\n    TRelations extends Record<string, AnyRelation>,\n    TIndexes extends Record<string, Index> = Record<string, Index>,\n  >(\n    name: TTableName,\n    callback: (\n      builder: TableBuilder<{}, Record<string, AnyRelation>, Record<string, Index>>,\n    ) => TableBuilder<TColumns, TRelations, TIndexes>,\n  ): SchemaBuilder<TTables & Record<TTableName, Table<TColumns, TRelations, TIndexes>>> {\n    this.#version++;\n\n    if (this.#tableNames.has(name)) {\n      throw new Error(`Duplicate table name \"${name}\" in schema \"${this.#name}\".`);\n    }\n\n    const tableBuilder = new TableBuilder<{}, Record<string, AnyRelation>, Record<string, Index>>(\n      name,\n    );\n    const result = callback(tableBuilder);\n    const builtTable = result.build();\n    const indexNames = result.getIndexes().map((idx) => idx.name);\n\n    for (const indexName of indexNames) {\n      if (this.#indexNames.has(indexName)) {\n        throw new Error(\n          `Duplicate index name \"${indexName}\" in schema \"${this.#name}\". Index names must be unique across tables (conflict on \"${name}\").`,\n        );\n      }\n    }\n\n    // Collect sub-operations in order\n    const subOperations: TableSubOperation[] = [];\n\n    // Add user-defined columns first\n    const columnOrder = result.getColumnOrder();\n    for (const colName of columnOrder) {\n      const col = builtTable.columns[colName];\n      subOperations.push({\n        type: \"add-column\",\n        columnName: colName,\n        column: cloneColumn(col),\n      });\n    }\n\n    // Add system columns (_internalId and _version) that were auto-added\n    if (builtTable.columns[\"_internalId\"]) {\n      subOperations.push({\n        type: \"add-column\",\n        columnName: \"_internalId\",\n        column: cloneColumn(builtTable.columns[\"_internalId\"]),\n      });\n    }\n    if (builtTable.columns[\"_version\"]) {\n      subOperations.push({\n        type: \"add-column\",\n        columnName: \"_version\",\n        column: cloneColumn(builtTable.columns[\"_version\"]),\n      });\n    }\n\n    // Add indexes from builder\n    for (const idx of result.getIndexes()) {\n      subOperations.push({\n        type: \"add-index\",\n        name: idx.name,\n        columns: idx.columns.map((c) => c.name),\n        unique: idx.unique,\n      });\n    }\n\n    // Add the add-table operation\n    this.#operations.push({\n      type: \"add-table\",\n      tableName: name,\n      operations: subOperations,\n    });\n\n    // Update tables map\n    this.#tables = { ...this.#tables, [name]: builtTable } as TTables &\n      Record<TTableName, Table<TColumns, TRelations, TIndexes>>;\n    this.#tableNames.add(name);\n    for (const indexName of indexNames) {\n      this.#indexNames.add(indexName);\n    }\n\n    return this as unknown as SchemaBuilder<\n      TTables & Record<TTableName, Table<TColumns, TRelations, TIndexes>>\n    >;\n  }\n\n  /**\n   * Add a relation between two tables.\n   *\n   * @param referenceName - A name for this relation (e.g., \"author\", \"posts\")\n   * @param config - Configuration specifying the relation type and foreign key mapping\n   *\n   * @example\n   * ```ts\n   * // One-to-one or many-to-one: post -> user\n   * schema(\"blog\", s => s\n   *   .addTable(\"users\", t => t.addColumn(\"id\", idColumn()))\n   *   .addTable(\"posts\", t => t\n   *     .addColumn(\"id\", idColumn())\n   *     .addColumn(\"userId\", referenceColumn()))\n   *   .addReference(\"author\", {\n   *     type: \"one\",\n   *     from: { table: \"posts\", column: \"userId\" },\n   *     to: { table: \"users\", column: \"id\" },\n   *   })\n   * )\n   *\n   * // One-to-many (inverse relation): user -> posts\n   * .addReference(\"posts\", {\n   *   type: \"many\",\n   *   from: { table: \"users\", column: \"id\" },\n   *   to: { table: \"posts\", column: \"userId\" },\n   * })\n   *\n   * // Self-referencing foreign key\n   * .addReference(\"inviter\", {\n   *   type: \"one\",\n   *   from: { table: \"users\", column: \"invitedBy\" },\n   *   to: { table: \"users\", column: \"id\" },\n   * })\n   *\n   * // Join-only relation (no foreign key)\n   * .addReference(\"invitedUser\", {\n   *   type: \"one\",\n   *   from: { table: \"invitations\", column: \"email\" },\n   *   to: { table: \"users\", column: \"email\" },\n   *   foreignKey: false,\n   * })\n   * ```\n   */\n  addReference<\n    TFromTableName extends string & keyof TTables,\n    TToTableName extends string & keyof TTables,\n    TReferenceName extends string,\n    TRelationType extends RelationType,\n  >(\n    referenceName: TReferenceName,\n    config: {\n      type: TRelationType;\n      from: {\n        table: TFromTableName;\n        column: keyof TTables[TFromTableName][\"columns\"];\n      };\n      to: {\n        table: TToTableName;\n        column: keyof TTables[TToTableName][\"columns\"];\n      };\n      /**\n       * When false, defines a join-only relation without foreign key migrations.\n       * References to external-id columns still coerce to `_internalId`\n       * (including left-side external IDs for join-only).\n       */\n      foreignKey?: boolean;\n    },\n  ): SchemaBuilder<\n    UpdateTableRelations<TTables, TFromTableName, TReferenceName, TToTableName, TRelationType>\n  > {\n    this.#version++;\n\n    const table = this.#tables[config.from.table];\n    const referencedTable = this.#tables[config.to.table];\n\n    if (!referenceName || referenceName.trim().length === 0) {\n      throw new Error(`referenceName is required for addReference on ${config.from.table}`);\n    }\n\n    if (!table) {\n      throw new Error(`Table ${config.from.table} not found in schema`);\n    }\n    if (!referencedTable) {\n      throw new Error(`Referenced table ${config.to.table} not found in schema`);\n    }\n\n    const columnName = config.from.column as string;\n    const targetColumnName = config.to.column as string;\n    const foreignKey = config.foreignKey !== false;\n\n    const column = table.columns[columnName];\n    const targetColumn = referencedTable.columns[targetColumnName];\n\n    if (!column) {\n      throw new Error(`Column ${columnName} not found in table ${config.from.table}`);\n    }\n    if (!targetColumn) {\n      throw new Error(`Column ${targetColumnName} not found in table ${config.to.table}`);\n    }\n\n    // External-id columns always target the internal ID column.\n    const actualTargetColumnName =\n      targetColumn.role === \"external-id\"\n        ? referencedTable.getInternalIdColumn().name\n        : targetColumnName;\n\n    const referencedColumn = referencedTable.columns[actualTargetColumnName];\n    if (!referencedColumn) {\n      throw new Error(`Column ${actualTargetColumnName} not found in table ${config.to.table}`);\n    }\n\n    if (table.relations[referenceName]) {\n      throw new Error(`Reference ${referenceName} already exists on table ${config.from.table}`);\n    }\n\n    // Verify that reference columns are bigint (matching internal ID type)\n    if (column.role === \"reference\" && column.type !== \"bigint\") {\n      throw new Error(\n        `Reference column ${columnName} must be of type bigint to match internal ID type`,\n      );\n    }\n\n    if (!foreignKey) {\n      const missingIndexes: string[] = [];\n      if (!this.#isJoinColumnIndexed(table, columnName)) {\n        missingIndexes.push(`${table.name}.${columnName}`);\n      }\n      if (!this.#isJoinColumnIndexed(referencedTable, actualTargetColumnName)) {\n        missingIndexes.push(`${referencedTable.name}.${actualTargetColumnName}`);\n      }\n      if (missingIndexes.length > 0) {\n        throw new Error(\n          `Join-only relation \"${referenceName}\" requires indexed join columns: ${missingIndexes.join(\", \")}.`,\n        );\n      }\n    }\n\n    // Join-only relations treat external IDs as internal IDs on the left side.\n    const actualFromColumnName =\n      !foreignKey && column.role === \"external-id\" ? table.getInternalIdColumn().name : columnName;\n\n    // Create the relation (use user-facing right-side column name)\n    const init = new ExplicitRelationInit(config.type, referencedTable, table, { foreignKey });\n    init.on.push([actualFromColumnName, targetColumnName]);\n    const relation = init.init(referenceName);\n\n    // Add relation to the table\n    table.relations[referenceName] = relation;\n\n    // Record the operation\n    this.#operations.push({\n      type: \"add-reference\",\n      tableName: config.from.table,\n      referenceName,\n      config: {\n        type: config.type,\n        from: { table: config.from.table, column: actualFromColumnName },\n        to: { table: config.to.table, column: actualTargetColumnName },\n        foreignKey,\n      },\n    });\n\n    // Return this with updated type\n    // Safe: The relation was added to the table in place and now has the updated relations\n    return this as unknown as SchemaBuilder<\n      UpdateTableRelations<TTables, TFromTableName, TReferenceName, TToTableName, TRelationType>\n    >;\n  }\n\n  /**\n   * Alter an existing table by adding columns, altering columns, or adding indexes.\n   * This is used for forward-only schema modifications.\n   *\n   * @param tableName - The name of the table to modify\n   * @param callback - A callback that receives a table builder for adding columns/indexes\n   *\n   * @example\n   * ```ts\n   * // Add a new column to an existing table\n   * schema(\"blog\", s => s\n   *   .addTable(\"users\", t => t\n   *     .addColumn(\"id\", idColumn())\n   *     .addColumn(\"name\", column(\"string\")))\n   *   .alterTable(\"users\", t => t\n   *     .alterColumn(\"name\").nullable()\n   *     .addColumn(\"email\", column(\"string\"))\n   *     .addColumn(\"age\", column(\"integer\").nullable())\n   *     .createIndex(\"idx_email\", [\"email\"]))\n   * )\n   * ```\n   */\n  alterTable<\n    TTableName extends string & keyof TTables,\n    TNewColumns extends Record<string, AnyColumn>,\n    TNewRelations extends Record<string, AnyRelation>,\n    TNewIndexes extends Record<string, Index> = Record<string, Index>,\n  >(\n    tableName: TTableName,\n    callback: (\n      builder: TableBuilder<\n        TTables[TTableName][\"columns\"],\n        TTables[TTableName][\"relations\"],\n        Record<string, Index>\n      >,\n    ) => TableBuilder<TNewColumns, TNewRelations, TNewIndexes>,\n  ): SchemaBuilder<UpdateTable<TTables, TTableName, TNewColumns, TNewRelations, TNewIndexes>> {\n    const table = this.#tables[tableName];\n\n    if (!table) {\n      throw new Error(`Table ${tableName} not found in schema`);\n    }\n\n    // Create builder with existing table state\n    const tableBuilder = new TableBuilder(tableName);\n    tableBuilder.setColumns(table.columns);\n    tableBuilder.setRelations(table.relations);\n    tableBuilder.setIndexes(table.indexes);\n\n    // Track existing columns and indexes\n    const existingColumns = new Set(Object.keys(table.columns));\n    const existingIndexes = new Set(Object.keys(table.indexes));\n    const existingColumnState = new Map<string, { isNullable: boolean }>();\n    for (const [colName, col] of Object.entries(table.columns)) {\n      existingColumnState.set(colName, { isNullable: col.isNullable });\n    }\n\n    // Apply modifications\n    const resultBuilder = callback(\n      tableBuilder as TableBuilder<\n        TTables[TTableName][\"columns\"],\n        TTables[TTableName][\"relations\"],\n        Record<string, Index>\n      >,\n    );\n    const newTable = resultBuilder.build();\n\n    // Collect sub-operations\n    const subOperations: TableSubOperation[] = [];\n\n    // Find new columns (preserve order from builder)\n    const columnOrder = resultBuilder.getColumnOrder();\n    for (const colName of columnOrder) {\n      if (!existingColumns.has(colName)) {\n        subOperations.push({\n          type: \"add-column\",\n          columnName: colName,\n          column: cloneColumn(newTable.columns[colName]),\n        });\n      }\n    }\n\n    // Track updates to existing columns\n    for (const [colName, previousState] of existingColumnState.entries()) {\n      const updatedColumn = newTable.columns[colName];\n      if (!updatedColumn) {\n        continue;\n      }\n      if (previousState.isNullable !== updatedColumn.isNullable) {\n        subOperations.push({\n          type: \"update-column\",\n          columnName: colName,\n          column: cloneColumn(updatedColumn),\n          updateNullable: true,\n          updateDefault: false,\n          updateDataType: false,\n        });\n      }\n    }\n\n    // Add only new indexes\n    for (const idx of resultBuilder.getIndexes()) {\n      if (!existingIndexes.has(idx.name)) {\n        if (this.#indexNames.has(idx.name)) {\n          throw new Error(\n            `Duplicate index name \"${idx.name}\" in schema \"${this.#name}\". Index names must be unique across tables (conflict on \"${tableName}\").`,\n          );\n        }\n        subOperations.push({\n          type: \"add-index\",\n          name: idx.name,\n          columns: idx.columns.map((c) => c.name),\n          unique: idx.unique,\n        });\n      }\n    }\n\n    if (subOperations.length > 0) {\n      this.#version++;\n      this.#operations.push({\n        type: \"alter-table\",\n        tableName,\n        operations: subOperations,\n      });\n    }\n\n    // Update table reference in schema\n    this.#tables[tableName] = newTable as unknown as TTables[TTableName];\n    this.#rebindRelations(tableName, newTable as unknown as AnyTable);\n    for (const idx of resultBuilder.getIndexes()) {\n      if (!existingIndexes.has(idx.name)) {\n        this.#indexNames.add(idx.name);\n      }\n    }\n\n    // Set table name for all columns\n    for (const col of Object.values(newTable.columns)) {\n      col.tableName = newTable.name;\n    }\n\n    return this as unknown as SchemaBuilder<\n      UpdateTable<TTables, TTableName, TNewColumns, TNewRelations, TNewIndexes>\n    >;\n  }\n\n  /**\n   * Build the final schema. This should be called after all tables are added.\n   */\n  build(): Schema<TTables> {\n    const operations = this.#operations;\n    const version = this.#version;\n    const tables = this.#tables;\n\n    const schema: Schema<TTables> = {\n      name: this.#name,\n      version,\n      tables,\n      operations,\n      clone: () => {\n        const cloneTables: Record<string, AnyTable> = {};\n\n        for (const [k, v] of Object.entries(tables)) {\n          // Create a new table with cloned columns\n          const clonedColumns: Record<string, AnyColumn> = {};\n          for (const [colName, col] of Object.entries(v.columns)) {\n            // Create a new column with the same properties, preserving the column type\n            let clonedCol: AnyColumn;\n            if (col instanceof InternalIdColumn) {\n              clonedCol = new InternalIdColumn();\n            } else if (col instanceof VersionColumn) {\n              clonedCol = new VersionColumn();\n            } else if (col instanceof IdColumn) {\n              clonedCol = new IdColumn(col.type);\n            } else {\n              clonedCol = new Column(col.type);\n            }\n\n            clonedCol.name = col.name;\n            clonedCol.isNullable = col.isNullable;\n            clonedCol.role = col.role;\n            clonedCol.isHidden = col.isHidden;\n            clonedCol.default = col.default;\n            clonedCol.tableName = col.tableName;\n            clonedColumns[colName] = clonedCol;\n          }\n\n          const clonedTable = {\n            ...v,\n            columns: clonedColumns,\n          } as AnyTable;\n\n          clonedTable[\"~standard\"] = createTableStandardSchemaProps(clonedTable, validationClasses);\n          clonedTable.validate = createTableValidator(clonedTable, validationClasses);\n\n          cloneTables[k] = clonedTable;\n        }\n\n        const clonedSchema: Schema<TTables> = {\n          name: this.#name,\n          version,\n          tables: cloneTables as TTables,\n          operations: [...operations],\n          clone: () => {\n            throw new Error(\"Cannot clone during clone\");\n          },\n        };\n\n        return new SchemaBuilder<TTables>(this.#name, clonedSchema).build();\n      },\n    };\n\n    return schema;\n  }\n\n  /**\n   * Get the current version of the schema builder.\n   */\n  getVersion(): number {\n    return this.#version;\n  }\n}\n\n/**\n * Create a new schema with callback pattern.\n */\nexport function schema<const TTables extends Record<string, AnyTable> = {}>(\n  name: string,\n  callback: (builder: SchemaBuilder<{}>) => SchemaBuilder<TTables>,\n): Schema<TTables> {\n  return callback(new SchemaBuilder(name)).build();\n}\n\nexport function compileForeignKey(key: ForeignKey) {\n  return {\n    name: key.name,\n    table: key.table.name,\n    referencedTable: key.referencedTable.name,\n    referencedColumns: key.referencedColumns.map((col) => col.name),\n    columns: key.columns.map((col) => col.name),\n  };\n}\n"],"mappings":";;;;;;;;;;;AAmkBA,IAAa,WAAb,MAAa,SAAS;CACpB,CAASA;CACT,CAASC;CACT,CAASC;CAET,YAAY,EACV,YACA,YACA,WAKC;AACD,QAAKF,aAAc;AACnB,QAAKC,aAAc;AACnB,QAAKC,UAAW;;;;;CAMlB,OAAO,aAAa,YAAoB,SAA2B;AACjE,SAAO,IAAI,SAAS;GAAE;GAAY;GAAS,CAAC;;CAG9C,IAAI,UAAkB;AACpB,SAAO,MAAKA;;CAGd,IAAI,aAAqB;AACvB,SAAO,MAAKF;;CAGd,IAAI,aAAiC;AACnC,SAAO,MAAKC;;;;;;CAOd,IAAI,aAA8B;AAChC,SAAO,MAAKA,cAAe,MAAKD;;;;;CAMlC,SAAsD;AACpD,SAAO;GACL,YAAY,MAAKA;GACjB,YAAY,MAAKC,YAAa,UAAU;GACzC;;CAGH,WAAmB;AACjB,SAAO,MAAKD;;CAGd,UAAkB;AAChB,SAAO,MAAKA;;;;;;;;;AAUhB,IAAa,kBAAb,MAAa,gBAAgB;CAC3B,CAASC;CAET,YAAY,YAAoB;AAC9B,QAAKA,aAAc;;;;;CAMrB,OAAO,aAAa,YAAqC;AACvD,SAAO,IAAI,gBAAgB,WAAW;;;;;CAMxC,IAAI,aAAqB;AACvB,SAAO,MAAKA"}

package/dist/browser/schema/generate-id.js

@@ -0,0 +1,28 @@
+import { FragnoId } from "./create.js";
+
+//#region src/schema/generate-id.ts
+/**
+* Generate a new ID for a table without creating a record.
+* This is useful when you need to reference an ID before actually creating the record,
+* or when you need to pass the ID to external services.
+*
+* @example
+* ```ts
+* const userId = generateId(mySchema, "users");
+* // Use userId in related records or pass to external services
+* uow.create("users", { id: userId, name: "John" });
+* ```
+*/
+function generateId(schema, tableName) {
+	const tableSchema = schema.tables[tableName];
+	if (!tableSchema) throw new Error(`Table ${tableName} not found in schema`);
+	const idColumn = tableSchema.getIdColumn();
+	const generated = idColumn.generateDefaultValue();
+	if (generated === void 0) throw new Error(`ID column ${idColumn.name} on table ${tableName} has no default generator`);
+	if (typeof generated !== "string") throw new Error(`ID column ${idColumn.name} on table ${tableName} has no default generator that generates a string.`);
+	return FragnoId.fromExternal(generated, 0);
+}
+
+//#endregion
+export { generateId };
+//# sourceMappingURL=generate-id.js.map

package/dist/browser/schema/generate-id.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"generate-id.js","names":[],"sources":["../../../src/schema/generate-id.ts"],"sourcesContent":["import type { AnySchema } from \"./create\";\nimport { FragnoId } from \"./create\";\n\n/**\n * Generate a new ID for a table without creating a record.\n * This is useful when you need to reference an ID before actually creating the record,\n * or when you need to pass the ID to external services.\n *\n * @example\n * ```ts\n * const userId = generateId(mySchema, \"users\");\n * // Use userId in related records or pass to external services\n * uow.create(\"users\", { id: userId, name: \"John\" });\n * ```\n */\nexport function generateId<\n  TSchema extends AnySchema,\n  TableName extends keyof TSchema[\"tables\"] & string,\n>(schema: TSchema, tableName: TableName): FragnoId {\n  const tableSchema = schema.tables[tableName];\n  if (!tableSchema) {\n    throw new Error(`Table ${tableName} not found in schema`);\n  }\n\n  const idColumn = tableSchema.getIdColumn();\n  const generated = idColumn.generateDefaultValue();\n  if (generated === undefined) {\n    throw new Error(`ID column ${idColumn.name} on table ${tableName} has no default generator`);\n  }\n\n  if (typeof generated !== \"string\") {\n    throw new Error(\n      `ID column ${idColumn.name} on table ${tableName} has no default generator that generates a string.`,\n    );\n  }\n\n  return FragnoId.fromExternal(generated, 0);\n}\n"],"mappings":";;;;;;;;;;;;;;;AAeA,SAAgB,WAGd,QAAiB,WAAgC;CACjD,MAAM,cAAc,OAAO,OAAO;AAClC,KAAI,CAAC,YACH,OAAM,IAAI,MAAM,SAAS,UAAU,sBAAsB;CAG3D,MAAM,WAAW,YAAY,aAAa;CAC1C,MAAM,YAAY,SAAS,sBAAsB;AACjD,KAAI,cAAc,OAChB,OAAM,IAAI,MAAM,aAAa,SAAS,KAAK,YAAY,UAAU,2BAA2B;AAG9F,KAAI,OAAO,cAAc,SACvB,OAAM,IAAI,MACR,aAAa,SAAS,KAAK,YAAY,UAAU,oDAClD;AAGH,QAAO,SAAS,aAAa,WAAW,EAAE"}

package/dist/browser/shared/providers.d.ts

@@ -0,0 +1,6 @@
+//#region src/shared/providers.d.ts
+declare const sqlProviders: readonly ["sqlite", "cockroachdb", "mysql", "postgresql", "mssql"];
+type SQLProvider = (typeof sqlProviders)[number];
+//#endregion
+export { SQLProvider };
+//# sourceMappingURL=providers.d.ts.map

package/dist/browser/shared/providers.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"providers.d.ts","names":[],"sources":["../../../src/shared/providers.ts"],"sourcesContent":[],"mappings":";cAAa;KAQD,WAAA,WAAsB"}

package/dist/browser/sql-driver/connection/connection-provider.d.ts

@@ -0,0 +1,13 @@
+import { DatabaseConnection } from "../sql-driver.js";
+
+//#region src/sql-driver/connection/connection-provider.d.ts
+interface ConnectionProvider {
+  /**
+   * Provides a connection for the callback and takes care of disposing
+   * the connection after the callback has been run.
+   */
+  provideConnection<T>(consumer: (connection: DatabaseConnection) => Promise<T>): Promise<T>;
+}
+//#endregion
+export { ConnectionProvider };
+//# sourceMappingURL=connection-provider.d.ts.map

package/dist/browser/sql-driver/connection/connection-provider.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"connection-provider.d.ts","names":[],"sources":["../../../../src/sql-driver/connection/connection-provider.ts"],"sourcesContent":[],"mappings":";;;UAEiB,kBAAA;;AAAjB;;;EAKqE,iBAAA,CAAA,CAAA,CAAA,CAAA,QAAA,EAAA,CAAA,UAAA,EAAvB,kBAAuB,EAAA,GAAA,OAAA,CAAQ,CAAR,CAAA,CAAA,EAAa,OAAb,CAAqB,CAArB,CAAA"}

package/dist/browser/sql-driver/dialect-adapter/dialect-adapter.d.ts

@@ -0,0 +1,7 @@
+//#region src/sql-driver/dialect-adapter/dialect-adapter.d.ts
+interface DialectAdapter {
+  readonly supportsReturning: boolean;
+}
+//#endregion
+export { DialectAdapter };
+//# sourceMappingURL=dialect-adapter.d.ts.map

package/dist/browser/sql-driver/dialect-adapter/dialect-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"dialect-adapter.d.ts","names":[],"sources":["../../../../src/sql-driver/dialect-adapter/dialect-adapter.ts"],"sourcesContent":[],"mappings":";UAAiB,cAAA;EAAA,SAAA,iBAAc,EAAA,OAAA"}

package/dist/browser/sql-driver/driver/runtime-driver.d.ts

@@ -0,0 +1,23 @@
+import { DatabaseConnection, Driver, TransactionSettings } from "../sql-driver.js";
+
+//#region src/sql-driver/driver/runtime-driver.d.ts
+
+/**
+ * A small wrapper around {@link Driver} that makes sure the driver is
+ * initialized before it is used, only initialized and destroyed
+ * once etc.
+ */
+declare class RuntimeDriver implements Driver {
+  #private;
+  constructor(driver: Driver);
+  init(): Promise<void>;
+  acquireConnection(): Promise<DatabaseConnection>;
+  releaseConnection(connection: DatabaseConnection): Promise<void>;
+  beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void>;
+  commitTransaction(connection: DatabaseConnection): Promise<void>;
+  rollbackTransaction(connection: DatabaseConnection): Promise<void>;
+  destroy(): Promise<void>;
+}
+//#endregion
+export { RuntimeDriver };
+//# sourceMappingURL=runtime-driver.d.ts.map

package/dist/browser/sql-driver/driver/runtime-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"runtime-driver.d.ts","names":[],"sources":["../../../../src/sql-driver/driver/runtime-driver.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AA8DmF,cAhDtE,aAAA,YAAyB,MAgD6C,CAAA;EAInD,CAAA,OAAA;EAAqB,WAAA,CAAA,MAAA,EA7C/B,MA6C+B;EAInB,IAAA,CAAA,CAAA,EA5ClB,OA4CkB,CAAA,IAAA,CAAA;EAAqB,iBAAA,CAAA,CAAA,EAxB1B,OAwB0B,CAxBlB,kBAwBkB,CAAA;EAIpC,iBAAA,CAAA,UAAA,EAhBmB,kBAgBnB,CAAA,EAhBwC,OAgBxC,CAAA,IAAA,CAAA;EA5DmB,gBAAA,CAAA,UAAA,EAgDP,kBAhDO,EAAA,QAAA,EAgDuB,mBAhDvB,CAAA,EAgD6C,OAhD7C,CAAA,IAAA,CAAA;EAAM,iBAAA,CAAA,UAAA,EAoDZ,kBApDY,CAAA,EAoDS,OApDT,CAAA,IAAA,CAAA;kCAwDV,qBAAqB;aAIpC"}

package/dist/browser/sql-driver/query-executor/plugin.d.ts

@@ -0,0 +1,17 @@
+import { QueryResult } from "../sql-driver.js";
+
+//#region src/sql-driver/query-executor/plugin.d.ts
+
+interface GenericSQLPlugin {
+  /**
+   * This method is called for each query after it has been executed.
+   * You can modify the result and return the modified result.
+   */
+  transformResult(args: PluginTransformResultArgs): Promise<QueryResult<unknown>>;
+}
+interface PluginTransformResultArgs {
+  readonly result: QueryResult<unknown>;
+}
+//#endregion
+export { GenericSQLPlugin };
+//# sourceMappingURL=plugin.d.ts.map

package/dist/browser/sql-driver/query-executor/plugin.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plugin.d.ts","names":[],"sources":["../../../../src/sql-driver/query-executor/plugin.ts"],"sourcesContent":[],"mappings":";;;;UAWiB,gBAAA;;;;;wBAKO,4BAA4B,QAAQ;;UAG3C,yBAAA;mBACE"}

package/dist/browser/sql-driver/query-executor/query-executor.d.ts

@@ -0,0 +1,36 @@
+import { CompiledQuery, QueryResult } from "../sql-driver.js";
+import { GenericSQLPlugin } from "./plugin.js";
+import { ConnectionProvider } from "../connection/connection-provider.js";
+
+//#region src/sql-driver/query-executor/query-executor.d.ts
+
+/**
+ * This interface abstracts away the details of how to execute a query.
+ */
+interface QueryExecutor extends ConnectionProvider {
+  /**
+   * Returns all installed plugins.
+   */
+  get plugins(): ReadonlyArray<GenericSQLPlugin>;
+  /**
+   * Executes a compiled query and runs the result through all plugins'
+   * `transformResult` method.
+   */
+  executeQuery<R>(compiledQuery: CompiledQuery): Promise<QueryResult<R>>;
+  /**
+   * Returns a copy of this executor with a new connection provider.
+   */
+  withConnectionProvider(connectionProvider: ConnectionProvider): QueryExecutor;
+  /**
+   * Returns a copy of this executor with a plugin added as the
+   * last plugin.
+   */
+  withPlugin(plugin: GenericSQLPlugin): QueryExecutor;
+  /**
+   * Returns a copy of this executor without any plugins.
+   */
+  withoutPlugins(): QueryExecutor;
+}
+//#endregion
+export { QueryExecutor };
+//# sourceMappingURL=query-executor.d.ts.map

package/dist/browser/sql-driver/query-executor/query-executor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"query-executor.d.ts","names":[],"sources":["../../../../src/sql-driver/query-executor/query-executor.ts"],"sourcesContent":[],"mappings":";;;;;;;;;AAqCqB,UArBJ,aAAA,SAAsB,kBAqBlB,CAAA;EAAmB;;;EArBiB,IAAA,OAAA,EAAA,EAIxC,aAJwC,CAI1B,gBAJ0B,CAAA;;;;;iCAUxB,gBAAgB,QAAQ,YAAY;;;;6CAKxB,qBAAqB;;;;;qBAM7C,mBAAmB;;;;oBAKpB"}

package/dist/browser/sql-driver/sql-driver-adapter.d.ts

@@ -0,0 +1,29 @@
+import { CompiledQuery, Dialect, QueryResult } from "./sql-driver.js";
+import { RuntimeDriver } from "./driver/runtime-driver.js";
+import { GenericSQLPlugin } from "./query-executor/plugin.js";
+import { QueryExecutor } from "./query-executor/query-executor.js";
+
+//#region src/sql-driver/sql-driver-adapter.d.ts
+
+declare class SqlDriverAdapter {
+  #private;
+  constructor(dialect: Dialect);
+  constructor(dialect: Dialect, executor: QueryExecutor, driver: RuntimeDriver | null);
+  executeQuery(query: CompiledQuery): Promise<QueryResult<Record<string, unknown>>>;
+  transaction<T>(callback: (trx: SqlDriverAdapter) => Promise<T>): Promise<T>;
+  /**
+   * Returns a copy of this adapter with the given plugin installed.
+   */
+  withPlugin(plugin: GenericSQLPlugin): SqlDriverAdapter;
+  /**
+   * Returns a copy of this adapter without any plugins.
+   */
+  withoutPlugins(): SqlDriverAdapter;
+  /**
+   * Releases all resources and disconnects from the database.
+   */
+  destroy(): Promise<void>;
+}
+//#endregion
+export { SqlDriverAdapter };
+//# sourceMappingURL=sql-driver-adapter.d.ts.map

package/dist/browser/sql-driver/sql-driver-adapter.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-driver-adapter.d.ts","names":[],"sources":["../../../src/sql-driver/sql-driver-adapter.ts"],"sourcesContent":[],"mappings":";;;;;;;AAqBiE,cANpD,gBAAA,CAMoD;EAgBrC,CAAA,OAAA;EAAoC,WAAA,CAAA,OAAA,EAjBzC,OAiByC;EAAZ,WAAA,CAAA,OAAA,EAhB7B,OAgB6B,EAAA,QAAA,EAhBV,aAgBU,EAAA,MAAA,EAhBa,aAgBb,GAAA,IAAA;EAAR,YAAA,CAAA,KAAA,EAAhB,aAAgB,CAAA,EAAA,OAAA,CAAQ,WAAR,CAAoB,MAApB,CAAA,MAAA,EAAA,OAAA,CAAA,CAAA,CAAA;EAIL,WAAA,CAAA,CAAA,CAAA,CAAA,QAAA,EAAA,CAAA,GAAA,EAAA,gBAAA,EAAA,GAAqB,OAArB,CAA6B,CAA7B,CAAA,CAAA,EAAkC,OAAlC,CAA0C,CAA1C,CAAA;EAA6B;;;EAAK,UAAA,CAAA,MAAA,EAmCpD,gBAnCoD,CAAA,EAmCjC,gBAnCiC;EAmCpD;;;EAcF,cAAA,CAAA,CAAA,EAPC,gBAOD;EAAO;;;aAAP"}

package/dist/browser/sql-driver/sql-driver.d.ts

@@ -0,0 +1,38 @@
+import { DialectAdapter } from "./dialect-adapter/dialect-adapter.js";
+
+//#region src/sql-driver/sql-driver.d.ts
+
+interface CompiledQuery {
+  readonly sql: string;
+  readonly parameters: ReadonlyArray<unknown>;
+}
+interface DatabaseConnection {
+  executeQuery<R>(compiledQuery: CompiledQuery): Promise<QueryResult<R>>;
+}
+interface QueryResult<O> {
+  readonly numAffectedRows?: bigint;
+  readonly numChangedRows?: bigint;
+  readonly insertId?: bigint;
+  readonly rows: O[];
+}
+interface TransactionSettings {}
+interface Driver {
+  init(): Promise<void>;
+  acquireConnection(): Promise<DatabaseConnection>;
+  releaseConnection(connection: DatabaseConnection): Promise<void>;
+  beginTransaction(connection: DatabaseConnection, settings: TransactionSettings): Promise<void>;
+  commitTransaction(connection: DatabaseConnection): Promise<void>;
+  rollbackTransaction(connection: DatabaseConnection): Promise<void>;
+  destroy(): Promise<void>;
+}
+interface QueryCompiler {
+  compileQuery(node: unknown, queryId: unknown): CompiledQuery;
+}
+interface Dialect {
+  createDriver(): Driver;
+  createAdapter(): DialectAdapter;
+  createQueryCompiler(): QueryCompiler;
+}
+//#endregion
+export { CompiledQuery, DatabaseConnection, Dialect, Driver, QueryResult, TransactionSettings };
+//# sourceMappingURL=sql-driver.d.ts.map

package/dist/browser/sql-driver/sql-driver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sql-driver.d.ts","names":[],"sources":["../../../src/sql-driver/sql-driver.ts"],"sourcesContent":[],"mappings":";;;;AAgBiD,UANhC,aAAA,CAMgC;EAAO,SAAA,GAAA,EAAA,MAAA;EAGvC,SAAA,UAAW,EAPL,aAYL,CAAA,OAAA,CAAA;AAGlB;AAIiB,UAhBA,kBAAA,CAgBM;EACb,YAAA,CAAA,CAAA,CAAA,CAAA,aAAA,EAhBuB,aAgBvB,CAAA,EAhBuC,OAgBvC,CAhB+C,WAgB/C,CAhB2D,CAgB3D,CAAA,CAAA;;AAEa,UAfN,WAeM,CAAA,CAAA,CAAA,CAAA;EACS,SAAA,eAAA,CAAA,EAAA,MAAA;EAAqB,SAAA,cAAA,CAAA,EAAA,MAAA;EAEtB,SAAA,QAAA,CAAA,EAAA,MAAA;EAA8B,SAAA,IAAA,EAb5C,CAa4C,EAAA;;AAC7B,UAXf,mBAAA,CAWe;AACE,UARjB,MAAA,CAQiB;EAAqB,IAAA,EAAA,EAP7C,OAO6C,CAAA,IAAA,CAAA;EAE1C,iBAAA,EAAA,EAPU,OAOV,CAPkB,kBAOlB,CAAA;EAAO,iBAAA,CAAA,UAAA,EANY,kBAMZ,CAAA,EANiC,OAMjC,CAAA,IAAA,CAAA;EAGH,gBAAa,CAAA,UAAA,EAPC,kBAQ+B,EAAA,QAAA,EARD,mBAQC,CAAA,EARqB,OAQrB,CAAA,IAAA,CAAA;EAG7C,iBAAO,CAAA,UAAA,EAVQ,kBAUR,CAAA,EAV6B,OAU7B,CAAA,IAAA,CAAA;EACN,mBAAA,CAAA,UAAA,EAVgB,kBAUhB,CAAA,EAVqC,OAUrC,CAAA,IAAA,CAAA;EACC,OAAA,EAAA,EATN,OASM,CAAA,IAAA,CAAA;;AACmB,UAPrB,aAAA,CAOqB;iDANW;;UAGhC,OAAA;kBACC;mBACC;yBACM"}

package/dist/browser/sync/commands.d.ts

@@ -0,0 +1,15 @@
+import { AnySchema } from "../schema/create.js";
+import { SyncCommandDefinition, SyncCommandRegistry } from "./types.js";
+
+//#region src/sync/commands.d.ts
+type DefineSyncCommandsContext = {
+  defineCommand: <TInput, TContext>(definition: SyncCommandDefinition<TInput, TContext>) => SyncCommandDefinition<TInput, TContext>;
+};
+declare const defineSyncCommands: <TSchema extends AnySchema>(options: {
+  schema: TSchema;
+}) => {
+  create: <const TCommands extends readonly SyncCommandDefinition[]>(factory: (context: DefineSyncCommandsContext) => TCommands) => SyncCommandRegistry;
+};
+//#endregion
+export { defineSyncCommands };
+//# sourceMappingURL=commands.d.ts.map

package/dist/browser/sync/commands.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.d.ts","names":[],"sources":["../../../src/sync/commands.ts"],"sourcesContent":[],"mappings":";;;;KAGK,yBAAA;gDAEW,sBAAsB,QAAQ,cACvC,sBAAsB,QAAQ;AALqC,CAAA;AAIpC,cAmCzB,kBAnCyB,EAAA,CAAA,gBAmCa,SAnCb,CAAA,CAAA,OAAA,EAAA;EAAQ,MAAA,EAmCmC,OAnCnC;CAA9B,EAAA,GAAA;EACa,MAAA,EAAA,CAAA,wBAAA,SAqCiB,qBArCjB,EAAA,CAAA,CAAA,OAAA,EAAA,CAAA,OAAA,EAsCJ,yBAtCI,EAAA,GAsC0B,SAtC1B,EAAA,GAuCtB,mBAvCsB;CAAQ"}

package/dist/browser/sync/commands.js

@@ -0,0 +1,27 @@
+//#region src/sync/commands.ts
+const createRegistry = (schemaName, commandList) => {
+	const commands = /* @__PURE__ */ new Map();
+	for (const command of commandList) {
+		if (!command || typeof command !== "object") throw new Error("Sync commands must be objects.");
+		const name = command.name;
+		if (typeof name !== "string" || name.trim().length === 0) throw new Error("Sync command name must be a non-empty string.");
+		const existing = commands.get(name);
+		if (existing && existing !== command) throw new Error(`Sync command "${name}" is already defined for schema "${schemaName}".`);
+		commands.set(name, command);
+	}
+	return {
+		schemaName,
+		commands,
+		getCommand: (name) => commands.get(name)
+	};
+};
+const defineSyncCommands = (options) => {
+	const schemaName = options.schema.name;
+	return { create: (factory) => {
+		return createRegistry(schemaName, factory({ defineCommand: (definition) => definition }));
+	} };
+};
+
+//#endregion
+export { defineSyncCommands };
+//# sourceMappingURL=commands.js.map

package/dist/browser/sync/commands.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"commands.js","names":[],"sources":["../../../src/sync/commands.ts"],"sourcesContent":["import type { AnySchema } from \"../schema/create\";\nimport type { SyncCommandDefinition, SyncCommandRegistry } from \"./types\";\n\ntype DefineSyncCommandsContext = {\n  defineCommand: <TInput, TContext>(\n    definition: SyncCommandDefinition<TInput, TContext>,\n  ) => SyncCommandDefinition<TInput, TContext>;\n};\n\nconst createRegistry = (\n  schemaName: string,\n  commandList: readonly SyncCommandDefinition[],\n): SyncCommandRegistry => {\n  const commands = new Map<string, SyncCommandDefinition>();\n\n  for (const command of commandList) {\n    if (!command || typeof command !== \"object\") {\n      throw new Error(\"Sync commands must be objects.\");\n    }\n\n    const name = command.name;\n    if (typeof name !== \"string\" || name.trim().length === 0) {\n      throw new Error(\"Sync command name must be a non-empty string.\");\n    }\n\n    const existing = commands.get(name);\n    if (existing && existing !== command) {\n      throw new Error(`Sync command \"${name}\" is already defined for schema \"${schemaName}\".`);\n    }\n\n    commands.set(name, command);\n  }\n\n  return {\n    schemaName,\n    commands,\n    getCommand: (name) => commands.get(name),\n  };\n};\n\nexport const defineSyncCommands = <TSchema extends AnySchema>(options: { schema: TSchema }) => {\n  const schemaName = options.schema.name;\n  return {\n    create: <const TCommands extends readonly SyncCommandDefinition[]>(\n      factory: (context: DefineSyncCommandsContext) => TCommands,\n    ): SyncCommandRegistry => {\n      const commands = factory({ defineCommand: (definition) => definition });\n      return createRegistry(schemaName, commands);\n    },\n  };\n};\n"],"mappings":";AASA,MAAM,kBACJ,YACA,gBACwB;CACxB,MAAM,2BAAW,IAAI,KAAoC;AAEzD,MAAK,MAAM,WAAW,aAAa;AACjC,MAAI,CAAC,WAAW,OAAO,YAAY,SACjC,OAAM,IAAI,MAAM,iCAAiC;EAGnD,MAAM,OAAO,QAAQ;AACrB,MAAI,OAAO,SAAS,YAAY,KAAK,MAAM,CAAC,WAAW,EACrD,OAAM,IAAI,MAAM,gDAAgD;EAGlE,MAAM,WAAW,SAAS,IAAI,KAAK;AACnC,MAAI,YAAY,aAAa,QAC3B,OAAM,IAAI,MAAM,iBAAiB,KAAK,mCAAmC,WAAW,IAAI;AAG1F,WAAS,IAAI,MAAM,QAAQ;;AAG7B,QAAO;EACL;EACA;EACA,aAAa,SAAS,SAAS,IAAI,KAAK;EACzC;;AAGH,MAAa,sBAAiD,YAAiC;CAC7F,MAAM,aAAa,QAAQ,OAAO;AAClC,QAAO,EACL,SACE,YACwB;AAExB,SAAO,eAAe,YADL,QAAQ,EAAE,gBAAgB,eAAe,YAAY,CAAC,CAC5B;IAE9C"}

package/dist/browser/sync/types.d.ts

@@ -0,0 +1,63 @@
+import { ExecuteTxOptions, HandlerTxBuilder } from "../query/unit-of-work/execute-unit-of-work.js";
+import { OutboxEntry } from "../outbox/outbox.js";
+import { RequestThisContext } from "@fragno-dev/core";
+
+//#region src/sync/types.d.ts
+type SubmitRequest = {
+  baseVersionstamp?: string;
+  requestId: string;
+  conflictResolutionStrategy: "server" | "disabled";
+  adapterIdentity: string;
+  commands: Array<{
+    id: string;
+    name: string;
+    target: {
+      fragment: string;
+      schema: string;
+    };
+    input: unknown;
+  }>;
+};
+type SubmitConflictReason = "conflict" | "write_congestion" | "client_far_behind" | "no_commands" | "already_handled" | "limit_exceeded";
+type SubmitAppliedResponse = {
+  status: "applied";
+  requestId: string;
+  confirmedCommandIds: string[];
+  lastVersionstamp?: string;
+  entries: OutboxEntry[];
+};
+type SubmitConflictResponse = {
+  status: "conflict";
+  requestId: string;
+  confirmedCommandIds: string[];
+  conflictCommandId?: string;
+  lastVersionstamp?: string;
+  entries: OutboxEntry[];
+  reason: SubmitConflictReason;
+};
+type SubmitResponse = SubmitAppliedResponse | SubmitConflictResponse;
+type SyncCommandTxFactory = (options?: Omit<ExecuteTxOptions, "createUnitOfWork">) => HandlerTxBuilder<readonly [], [], [], unknown, unknown, false, false, false, false, {}>;
+type SyncCommandHandler<TInput = unknown, TContext = unknown> = (args: {
+  input: TInput;
+  tx: SyncCommandTxFactory;
+  ctx: TContext;
+}) => Promise<unknown>;
+type SyncCommandDefinition<TInput = unknown, TContext = unknown> = {
+  name: string;
+  handler: SyncCommandHandler<TInput, TContext>;
+  createServerContext?: (requestContext: RequestThisContext) => TContext;
+};
+type SyncCommandRegistry = {
+  schemaName: string;
+  commands: Map<string, SyncCommandDefinition>;
+  getCommand: (name: string) => SyncCommandDefinition | undefined;
+};
+type SyncCommandTargetRegistration = {
+  fragmentName: string;
+  schemaName: string;
+  namespace: string | null;
+  commands: Map<string, SyncCommandDefinition>;
+};
+//#endregion
+export { SubmitAppliedResponse, SubmitConflictReason, SubmitConflictResponse, SubmitRequest, SubmitResponse, SyncCommandDefinition, SyncCommandHandler, SyncCommandRegistry, SyncCommandTargetRegistration, SyncCommandTxFactory };
+//# sourceMappingURL=types.d.ts.map

package/dist/browser/sync/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/sync/types.ts"],"sourcesContent":[],"mappings":";;;;;KAQY,aAAA;;EAAA,SAAA,EAAA,MAAa;EAgBb,0BAAoB,EAAA,QAAA,GAAA,UAAA;EAQpB,eAAA,EAAA,MAAA;EAQA,QAAA,EA3BA,KA2BA,CAAA;IAUA,EAAA,EAAA,MAAA;IAEA,IAAA,EAAA,MAAA;IACK,MAAA,EAAA;MAAL,QAAA,EAAA,MAAA;MACP,MAAA,EAAA,MAAA;IAAgB,CAAA;IAET,KAAA,EAAA,OAAA;EACH,CAAA,CAAA;CACH;AACC,KAnCK,oBAAA,GAmCL,UAAA,GAAA,kBAAA,GAAA,mBAAA,GAAA,aAAA,GAAA,iBAAA,GAAA,gBAAA;AACD,KA5BM,qBAAA,GA4BN;EAAO,MAAA,EAAA,SAAA;EAED,SAAA,EAAA,MAAA;EAEkB,mBAAA,EAAA,MAAA,EAAA;EAAQ,gBAAA,CAAA,EAAA,MAAA;EAA3B,OAAA,EA3BA,WA2BA,EAAA;CAC8B;AAAuB,KAzBpD,sBAAA,GAyBoD;EAAQ,MAAA,EAAA,UAAA;EAG5D,SAAA,EAAA,MAAA;EAEY,mBAAA,EAAA,MAAA,EAAA;EAAZ,iBAAA,CAAA,EAAA,MAAA;EACoB,gBAAA,CAAA,EAAA,MAAA;EAAqB,OAAA,EAzB1C,WAyB0C,EAAA;EAGzC,MAAA,EA3BF,oBA2BE;;KAxBA,cAAA,GAAiB,wBAAwB;KAEzC,oBAAA,cACA,KAAK,0CACZ;KAEO;SACH;MACH;OACC;MACD;KAEM;;WAED,mBAAmB,QAAQ;yCACG,uBAAuB;;KAGpD,mBAAA;;YAEA,YAAY;gCACQ;;KAGpB,6BAAA;;;;YAIA,YAAY"}

package/dist/browser/util/types.d.ts

@@ -0,0 +1,8 @@
+//#region src/util/types.d.ts
+/**
+ * Forces TypeScript to simplify/flatten complex intersection types for better display in IDE hovers
+ */
+type Prettify<T> = { [K in keyof T]: T[K] } & {};
+//#endregion
+export { Prettify };
+//# sourceMappingURL=types.d.ts.map

package/dist/browser/util/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","names":[],"sources":["../../../src/util/types.ts"],"sourcesContent":[],"mappings":";;AAGA;;AAA4C,KAAhC,QAAgC,CAAA,CAAA,CAAA,GAAA,QAAE,MAAN,CAAM,GAAF,CAAE,CAAA,CAAA,CAAA,EAAC,GAAA,CAAA,CAAA"}