syncorejs 0.1.0

package/dist/schema/src/definition.d.ts

@@ -0,0 +1,98 @@
+import { Infer, ObjectValidator, ObjectValidatorShape, Validator } from "./validators.js";
+
+//#region ../schema/src/definition.d.ts
+interface IndexDefinition {
+  name: string;
+  fields: string[];
+}
+interface SearchIndexDefinition {
+  name: string;
+  searchField: string;
+  filterFields: string[];
+}
+interface TableDefinitionOptions {
+  tableName?: string;
+}
+interface TableDocumentSystemFields {
+  _id: string;
+  _creationTime: number;
+}
+/**
+ * Describes a Syncore table and its indexes.
+ *
+ * Create tables with {@link defineTable} and then chain index helpers to make
+ * queries faster and more expressive.
+ */
+declare class TableDefinition<TValidator extends Validator<unknown>> {
+  readonly validator: TValidator;
+  readonly indexes: IndexDefinition[];
+  readonly searchIndexes: SearchIndexDefinition[];
+  readonly options: TableDefinitionOptions;
+  constructor(validator: TValidator, options?: TableDefinitionOptions);
+  /**
+   * Add a named index for querying a table by one or more fields.
+   *
+   * @param name - The index name used from `ctx.db.query(...).withIndex(...)`.
+   * @param fields - The fields that participate in the index.
+   * @returns The same table definition for chaining.
+   */
+  index(name: string, fields: string[]): this;
+  /**
+   * Add a search index for text search.
+   *
+   * @param name - The search index name used from `withSearchIndex(...)`.
+   * @param config - The indexed search field and optional filter fields.
+   * @returns The same table definition for chaining.
+   */
+  searchIndex(name: string, config: {
+    searchField: string;
+    filterFields?: string[];
+  }): this;
+}
+type AnyTableDefinition = TableDefinition<Validator<unknown>>;
+type InferDocument<TTable extends AnyTableDefinition> = Infer<TTable["validator"]> & TableDocumentSystemFields;
+type InferTableInput<TTable extends AnyTableDefinition> = Omit<InferDocument<TTable>, keyof TableDocumentSystemFields>;
+/**
+ * Define a table in a Syncore schema.
+ *
+ * Pass an object of validators describing the document fields stored in the
+ * table. Chain `.index(...)` or `.searchIndex(...)` to add query helpers.
+ *
+ * @example
+ * ```ts
+ * const tasks = defineTable({
+ *   text: v.string(),
+ *   done: v.boolean()
+ * }).index("by_done", ["done"]);
+ * ```
+ */
+declare function defineTable<TShape extends ObjectValidatorShape>(validator: TShape): TableDefinition<ObjectValidator<TShape>>;
+declare function defineTable<TValidator extends Validator<unknown>>(validator: TValidator): TableDefinition<TValidator>;
+interface SyncoreSchemaDefinition {
+  [tableName: string]: AnyTableDefinition;
+}
+declare class SyncoreSchema<TTables extends SyncoreSchemaDefinition> {
+  readonly tables: TTables;
+  constructor(tables: TTables);
+  getTable<TTableName extends Extract<keyof TTables, string>>(tableName: TTableName): TTables[TTableName];
+  tableNames(): Array<Extract<keyof TTables, string>>;
+}
+/**
+ * Define the tables that make up your Syncore app.
+ *
+ * The returned schema is used by runtimes, code generation, and type inference.
+ *
+ * @example
+ * ```ts
+ * export default defineSchema({
+ *   tasks: defineTable({
+ *     text: v.string(),
+ *     done: v.boolean()
+ *   })
+ * });
+ * ```
+ */
+declare function defineSchema<TTables extends SyncoreSchemaDefinition>(tables: TTables): SyncoreSchema<TTables>;
+//#endregion
+export { AnyTableDefinition, IndexDefinition, InferDocument, InferTableInput, SearchIndexDefinition, SyncoreSchema, SyncoreSchemaDefinition, TableDefinition, TableDefinitionOptions, TableDocumentSystemFields, defineSchema, defineTable };
+//# sourceMappingURL=definition.d.ts.map

package/dist/schema/src/definition.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.d.ts","names":[],"sources":["../../../../schema/src/definition.ts"],"mappings":";;;UAQiB,eAAA;EACf,IAAA;EACA,MAAA;AAAA;AAAA,UAGe,qBAAA;EACf,IAAA;EACA,WAAA;EACA,YAAA;AAAA;AAAA,UAGe,sBAAA;EACf,SAAA;AAAA;AAAA,UAGe,yBAAA;EACf,GAAA;EACA,aAAA;AAAA;;;;;AAFF;;cAWa,eAAA,oBAAmC,SAAA;EAAA,SAM5B,SAAA,EAAW,UAAA;EAAA,SALpB,OAAA,EAAS,eAAA;EAAA,SACT,aAAA,EAAe,qBAAA;EAAA,SACf,OAAA,EAAS,sBAAA;cAGA,SAAA,EAAW,UAAA,EAC3B,OAAA,GAAU,sBAAA;EAPkC;;;;;;;EAmB9C,KAAA,CAAM,IAAA,UAAc,MAAA;EAZc;;;;;;;EAwBlC,WAAA,CACE,IAAA,UACA,MAAA;IAAU,WAAA;IAAqB,YAAA;EAAA;AAAA;AAAA,KAWvB,kBAAA,GAAqB,eAAA,CAAgB,SAAA;AAAA,KAErC,aAAA,gBAA6B,kBAAA,IAAsB,KAAA,CAC7D,MAAA,iBAEA,yBAAA;AAAA,KAEU,eAAA,gBAA+B,kBAAA,IAAsB,IAAA,CAC/D,aAAA,CAAc,MAAA,SACR,yBAAA;;;;;;;;;;;;AATR;;;iBA0BgB,WAAA,gBAA2B,oBAAA,CAAA,CACzC,SAAA,EAAW,MAAA,GACV,eAAA,CAAgB,eAAA,CAAgB,MAAA;AAAA,iBACnB,WAAA,oBAA+B,SAAA,UAAA,CAC7C,SAAA,EAAW,UAAA,GACV,eAAA,CAAgB,UAAA;AAAA,UAOF,uBAAA;EAAA,CACd,SAAA,WAAoB,kBAAA;AAAA;AAAA,cAGV,aAAA,iBAA8B,uBAAA;EAAA,SACb,MAAA,EAAQ,OAAA;cAAR,MAAA,EAAQ,OAAA;EAEpC,QAAA,oBAA4B,OAAA,OAAc,OAAA,UAAA,CACxC,SAAA,EAAW,UAAA,GACV,OAAA,CAAQ,UAAA;EAQX,UAAA,CAAA,GAAc,KAAA,CAAM,OAAA,OAAc,OAAA;AAAA;;;;;;;;AAhDpC;;;;;;;;iBAoEgB,YAAA,iBAA6B,uBAAA,CAAA,CAC3C,MAAA,EAAQ,OAAA,GACP,aAAA,CAAc,OAAA"}

package/dist/schema/src/definition.js

@@ -0,0 +1,84 @@
+import { ensureObjectValidator } from "./validators.js";
+//#region ../schema/src/definition.ts
+/**
+* Describes a Syncore table and its indexes.
+*
+* Create tables with {@link defineTable} and then chain index helpers to make
+* queries faster and more expressive.
+*/
+var TableDefinition = class {
+	indexes = [];
+	searchIndexes = [];
+	options;
+	constructor(validator, options) {
+		this.validator = validator;
+		this.options = options ?? {};
+	}
+	/**
+	* Add a named index for querying a table by one or more fields.
+	*
+	* @param name - The index name used from `ctx.db.query(...).withIndex(...)`.
+	* @param fields - The fields that participate in the index.
+	* @returns The same table definition for chaining.
+	*/
+	index(name, fields) {
+		this.indexes.push({
+			name,
+			fields
+		});
+		return this;
+	}
+	/**
+	* Add a search index for text search.
+	*
+	* @param name - The search index name used from `withSearchIndex(...)`.
+	* @param config - The indexed search field and optional filter fields.
+	* @returns The same table definition for chaining.
+	*/
+	searchIndex(name, config) {
+		this.searchIndexes.push({
+			name,
+			searchField: config.searchField,
+			filterFields: config.filterFields ?? []
+		});
+		return this;
+	}
+};
+function defineTable(validator) {
+	return new TableDefinition(ensureObjectValidator(validator));
+}
+var SyncoreSchema = class {
+	constructor(tables) {
+		this.tables = tables;
+	}
+	getTable(tableName) {
+		const table = this.tables[tableName];
+		if (!table) throw new Error(`Unknown table "${tableName}".`);
+		return table;
+	}
+	tableNames() {
+		return Object.keys(this.tables);
+	}
+};
+/**
+* Define the tables that make up your Syncore app.
+*
+* The returned schema is used by runtimes, code generation, and type inference.
+*
+* @example
+* ```ts
+* export default defineSchema({
+*   tasks: defineTable({
+*     text: v.string(),
+*     done: v.boolean()
+*   })
+* });
+* ```
+*/
+function defineSchema(tables) {
+	return new SyncoreSchema(tables);
+}
+//#endregion
+export { SyncoreSchema, TableDefinition, defineSchema, defineTable };
+
+//# sourceMappingURL=definition.js.map

package/dist/schema/src/definition.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"definition.js","names":[],"sources":["../../../../schema/src/definition.ts"],"sourcesContent":["import {\r\n  ensureObjectValidator,\r\n  type Infer,\r\n  type ObjectValidatorShape,\r\n  type Validator\r\n} from \"./validators.js\";\r\nimport type { ObjectValidator } from \"./validators.js\";\r\n\r\nexport interface IndexDefinition {\r\n  name: string;\r\n  fields: string[];\r\n}\r\n\r\nexport interface SearchIndexDefinition {\r\n  name: string;\r\n  searchField: string;\r\n  filterFields: string[];\r\n}\r\n\r\nexport interface TableDefinitionOptions {\r\n  tableName?: string;\r\n}\r\n\r\nexport interface TableDocumentSystemFields {\r\n  _id: string;\r\n  _creationTime: number;\r\n}\r\n\r\n/**\r\n * Describes a Syncore table and its indexes.\r\n *\r\n * Create tables with {@link defineTable} and then chain index helpers to make\r\n * queries faster and more expressive.\r\n */\r\nexport class TableDefinition<TValidator extends Validator<unknown>> {\r\n  readonly indexes: IndexDefinition[] = [];\r\n  readonly searchIndexes: SearchIndexDefinition[] = [];\r\n  readonly options: TableDefinitionOptions;\r\n\r\n  constructor(\r\n    public readonly validator: TValidator,\r\n    options?: TableDefinitionOptions\r\n  ) {\r\n    this.options = options ?? {};\r\n  }\r\n\r\n  /**\r\n   * Add a named index for querying a table by one or more fields.\r\n   *\r\n   * @param name - The index name used from `ctx.db.query(...).withIndex(...)`.\r\n   * @param fields - The fields that participate in the index.\r\n   * @returns The same table definition for chaining.\r\n   */\r\n  index(name: string, fields: string[]): this {\r\n    this.indexes.push({ name, fields });\r\n    return this;\r\n  }\r\n\r\n  /**\r\n   * Add a search index for text search.\r\n   *\r\n   * @param name - The search index name used from `withSearchIndex(...)`.\r\n   * @param config - The indexed search field and optional filter fields.\r\n   * @returns The same table definition for chaining.\r\n   */\r\n  searchIndex(\r\n    name: string,\r\n    config: { searchField: string; filterFields?: string[] }\r\n  ): this {\r\n    this.searchIndexes.push({\r\n      name,\r\n      searchField: config.searchField,\r\n      filterFields: config.filterFields ?? []\r\n    });\r\n    return this;\r\n  }\r\n}\r\n\r\nexport type AnyTableDefinition = TableDefinition<Validator<unknown>>;\r\n\r\nexport type InferDocument<TTable extends AnyTableDefinition> = Infer<\r\n  TTable[\"validator\"]\r\n> &\r\n  TableDocumentSystemFields;\r\n\r\nexport type InferTableInput<TTable extends AnyTableDefinition> = Omit<\r\n  InferDocument<TTable>,\r\n  keyof TableDocumentSystemFields\r\n>;\r\n\r\n/**\r\n * Define a table in a Syncore schema.\r\n *\r\n * Pass an object of validators describing the document fields stored in the\r\n * table. Chain `.index(...)` or `.searchIndex(...)` to add query helpers.\r\n *\r\n * @example\r\n * ```ts\r\n * const tasks = defineTable({\r\n *   text: v.string(),\r\n *   done: v.boolean()\r\n * }).index(\"by_done\", [\"done\"]);\r\n * ```\r\n */\r\nexport function defineTable<TShape extends ObjectValidatorShape>(\r\n  validator: TShape\r\n): TableDefinition<ObjectValidator<TShape>>;\r\nexport function defineTable<TValidator extends Validator<unknown>>(\r\n  validator: TValidator\r\n): TableDefinition<TValidator>;\r\nexport function defineTable<TShape extends ObjectValidatorShape>(\r\n  validator: TShape | Validator<unknown>\r\n): TableDefinition<Validator<unknown>> {\r\n  return new TableDefinition(ensureObjectValidator(validator));\r\n}\r\n\r\nexport interface SyncoreSchemaDefinition {\r\n  [tableName: string]: AnyTableDefinition;\r\n}\r\n\r\nexport class SyncoreSchema<TTables extends SyncoreSchemaDefinition> {\r\n  constructor(public readonly tables: TTables) {}\r\n\r\n  getTable<TTableName extends Extract<keyof TTables, string>>(\r\n    tableName: TTableName\r\n  ): TTables[TTableName] {\r\n    const table = this.tables[tableName];\r\n    if (!table) {\r\n      throw new Error(`Unknown table \"${tableName}\".`);\r\n    }\r\n    return table;\r\n  }\r\n\r\n  tableNames(): Array<Extract<keyof TTables, string>> {\r\n    return Object.keys(this.tables) as Array<Extract<keyof TTables, string>>;\r\n  }\r\n}\r\n\r\n/**\r\n * Define the tables that make up your Syncore app.\r\n *\r\n * The returned schema is used by runtimes, code generation, and type inference.\r\n *\r\n * @example\r\n * ```ts\r\n * export default defineSchema({\r\n *   tasks: defineTable({\r\n *     text: v.string(),\r\n *     done: v.boolean()\r\n *   })\r\n * });\r\n * ```\r\n */\r\nexport function defineSchema<TTables extends SyncoreSchemaDefinition>(\r\n  tables: TTables\r\n): SyncoreSchema<TTables> {\r\n  return new SyncoreSchema(tables);\r\n}\r\n"],"mappings":";;;;;;;;AAkCA,IAAa,kBAAb,MAAoE;CAClE,UAAsC,EAAE;CACxC,gBAAkD,EAAE;CACpD;CAEA,YACE,WACA,SACA;AAFgB,OAAA,YAAA;AAGhB,OAAK,UAAU,WAAW,EAAE;;;;;;;;;CAU9B,MAAM,MAAc,QAAwB;AAC1C,OAAK,QAAQ,KAAK;GAAE;GAAM;GAAQ,CAAC;AACnC,SAAO;;;;;;;;;CAUT,YACE,MACA,QACM;AACN,OAAK,cAAc,KAAK;GACtB;GACA,aAAa,OAAO;GACpB,cAAc,OAAO,gBAAgB,EAAE;GACxC,CAAC;AACF,SAAO;;;AAoCX,SAAgB,YACd,WACqC;AACrC,QAAO,IAAI,gBAAgB,sBAAsB,UAAU,CAAC;;AAO9D,IAAa,gBAAb,MAAoE;CAClE,YAAY,QAAiC;AAAjB,OAAA,SAAA;;CAE5B,SACE,WACqB;EACrB,MAAM,QAAQ,KAAK,OAAO;AAC1B,MAAI,CAAC,MACH,OAAM,IAAI,MAAM,kBAAkB,UAAU,IAAI;AAElD,SAAO;;CAGT,aAAoD;AAClD,SAAO,OAAO,KAAK,KAAK,OAAO;;;;;;;;;;;;;;;;;;AAmBnC,SAAgB,aACd,QACwB;AACxB,QAAO,IAAI,cAAc,OAAO"}

package/dist/schema/src/planner.d.ts

@@ -0,0 +1,42 @@
+import { ValidatorDescription } from "./validators.js";
+import { SearchIndexDefinition, SyncoreSchema, SyncoreSchemaDefinition } from "./definition.js";
+
+//#region ../schema/src/planner.d.ts
+interface TableSnapshot {
+  name: string;
+  validator: ValidatorDescription;
+  indexes: Array<{
+    name: string;
+    fields: string[];
+  }>;
+  searchIndexes: Array<{
+    name: string;
+    searchField: string;
+    filterFields: string[];
+  }>;
+}
+interface SchemaSnapshot {
+  version: 1;
+  tables: TableSnapshot[];
+  hash: string;
+}
+interface SchemaMigrationPlan {
+  previousHash: string | null;
+  nextHash: string;
+  statements: string[];
+  warnings: string[];
+  destructiveChanges: string[];
+}
+declare function createSchemaSnapshot<TTables extends SyncoreSchemaDefinition>(schema: SyncoreSchema<TTables>): SchemaSnapshot;
+declare function diffSchemaSnapshots(previousSnapshot: SchemaSnapshot | null | undefined, nextSnapshot: SchemaSnapshot): SchemaMigrationPlan;
+declare function renderMigrationSql(plan: SchemaMigrationPlan, options?: {
+  title?: string;
+}): string;
+declare function parseSchemaSnapshot(source: string): SchemaSnapshot;
+declare function renderCreateTableStatement(tableName: string): string;
+declare function renderCreateIndexStatement(tableName: string, indexName: string, fields: string[]): string;
+declare function renderCreateSearchIndexStatement(tableName: string, searchIndex: SearchIndexDefinition | TableSnapshot["searchIndexes"][number]): string;
+declare function searchIndexTableName(tableName: string, indexName: string): string;
+//#endregion
+export { SchemaMigrationPlan, SchemaSnapshot, TableSnapshot, createSchemaSnapshot, diffSchemaSnapshots, parseSchemaSnapshot, renderCreateIndexStatement, renderCreateSearchIndexStatement, renderCreateTableStatement, renderMigrationSql, searchIndexTableName };
+//# sourceMappingURL=planner.d.ts.map

package/dist/schema/src/planner.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.d.ts","names":[],"sources":["../../../../schema/src/planner.ts"],"mappings":";;;;UAUiB,aAAA;EACf,IAAA;EACA,SAAA,EAAW,oBAAA;EACX,OAAA,EAAS,KAAA;IACP,IAAA;IACA,MAAA;EAAA;EAEF,aAAA,EAAe,KAAA;IACb,IAAA;IACA,WAAA;IACA,YAAA;EAAA;AAAA;AAAA,UAIa,cAAA;EACf,OAAA;EACA,MAAA,EAAQ,aAAA;EACR,IAAA;AAAA;AAAA,UAGe,mBAAA;EACf,YAAA;EACA,QAAA;EACA,UAAA;EACA,QAAA;EACA,kBAAA;AAAA;AAAA,iBAGc,oBAAA,iBAAqC,uBAAA,CAAA,CACnD,MAAA,EAAQ,aAAA,CAAc,OAAA,IACrB,cAAA;AAAA,iBAoCa,mBAAA,CACd,gBAAA,EAAkB,cAAA,qBAClB,YAAA,EAAc,cAAA,GACb,mBAAA;AAAA,iBAqGa,kBAAA,CACd,IAAA,EAAM,mBAAA,EACN,OAAA;EAAY,KAAA;AAAA;AAAA,iBA+BE,mBAAA,CAAoB,MAAA,WAAiB,cAAA;AAAA,iBAQrC,0BAAA,CAA2B,SAAA;AAAA,iBAS3B,0BAAA,CACd,SAAA,UACA,SAAA,UACA,MAAA;AAAA,iBAUc,gCAAA,CACd,SAAA,UACA,WAAA,EAAa,qBAAA,GAAwB,aAAA;AAAA,iBAOvB,oBAAA,CAAqB,SAAA,UAAmB,SAAA"}

package/dist/schema/src/planner.js

@@ -0,0 +1,131 @@
+import { describeValidator } from "./validators.js";
+//#region ../schema/src/planner.ts
+function createSchemaSnapshot(schema) {
+	const base = {
+		version: 1,
+		tables: schema.tableNames().sort((left, right) => left.localeCompare(right)).map((tableName) => {
+			const table = schema.getTable(tableName);
+			return {
+				name: tableName,
+				validator: describeValidator(table.validator),
+				indexes: table.indexes.map((index) => ({
+					name: index.name,
+					fields: [...index.fields]
+				})).sort((left, right) => left.name.localeCompare(right.name)),
+				searchIndexes: table.searchIndexes.map((index) => ({
+					name: index.name,
+					searchField: index.searchField,
+					filterFields: [...index.filterFields]
+				})).sort((left, right) => left.name.localeCompare(right.name))
+			};
+		})
+	};
+	return {
+		...base,
+		hash: createSchemaHash(base)
+	};
+}
+function diffSchemaSnapshots(previousSnapshot, nextSnapshot) {
+	const statements = [];
+	const warnings = [];
+	const destructiveChanges = [];
+	const previousTables = new Map((previousSnapshot?.tables ?? []).map((table) => [table.name, table]));
+	const nextTables = new Map(nextSnapshot.tables.map((table) => [table.name, table]));
+	for (const table of nextSnapshot.tables) {
+		const previousTable = previousTables.get(table.name);
+		if (!previousTable) {
+			statements.push(renderCreateTableStatement(table.name));
+			for (const index of table.indexes) statements.push(renderCreateIndexStatement(table.name, index.name, index.fields));
+			for (const searchIndex of table.searchIndexes) statements.push(renderCreateSearchIndexStatement(table.name, searchIndex));
+			continue;
+		}
+		if (stableStringify(previousTable.validator) !== stableStringify(table.validator)) warnings.push(`Validator changed for table "${table.name}". Existing rows are not rewritten automatically.`);
+		const previousIndexes = new Map(previousTable.indexes.map((index) => [index.name, index]));
+		const nextIndexes = new Map(table.indexes.map((index) => [index.name, index]));
+		for (const index of table.indexes) {
+			const previousIndex = previousIndexes.get(index.name);
+			if (!previousIndex) {
+				statements.push(renderCreateIndexStatement(table.name, index.name, index.fields));
+				continue;
+			}
+			if (stableStringify(previousIndex.fields) !== stableStringify(index.fields)) destructiveChanges.push(`Index "${table.name}.${index.name}" changed fields and requires a manual migration.`);
+		}
+		for (const previousIndex of previousTable.indexes) if (!nextIndexes.has(previousIndex.name)) destructiveChanges.push(`Index "${table.name}.${previousIndex.name}" was removed and requires a manual migration.`);
+		const previousSearchIndexes = new Map(previousTable.searchIndexes.map((index) => [index.name, index]));
+		const nextSearchIndexes = new Map(table.searchIndexes.map((index) => [index.name, index]));
+		for (const searchIndex of table.searchIndexes) {
+			const previousSearchIndex = previousSearchIndexes.get(searchIndex.name);
+			if (!previousSearchIndex) {
+				statements.push(renderCreateSearchIndexStatement(table.name, searchIndex));
+				continue;
+			}
+			if (stableStringify(previousSearchIndex) !== stableStringify(searchIndex)) destructiveChanges.push(`Search index "${table.name}.${searchIndex.name}" changed and requires a manual migration.`);
+		}
+		for (const previousSearchIndex of previousTable.searchIndexes) if (!nextSearchIndexes.has(previousSearchIndex.name)) destructiveChanges.push(`Search index "${table.name}.${previousSearchIndex.name}" was removed and requires a manual migration.`);
+	}
+	for (const previousTable of previousSnapshot?.tables ?? []) if (!nextTables.has(previousTable.name)) destructiveChanges.push(`Table "${previousTable.name}" was removed and requires a manual migration.`);
+	return {
+		previousHash: previousSnapshot?.hash ?? null,
+		nextHash: nextSnapshot.hash,
+		statements,
+		warnings,
+		destructiveChanges
+	};
+}
+function renderMigrationSql(plan, options) {
+	const lines = [];
+	lines.push(`-- ${options?.title ?? "Syncore migration"}`);
+	lines.push(`-- previous: ${plan.previousHash ?? "none"}`);
+	lines.push(`-- next: ${plan.nextHash}`);
+	for (const warning of plan.warnings) lines.push(`-- warning: ${warning}`);
+	if (plan.destructiveChanges.length > 0) for (const destructiveChange of plan.destructiveChanges) lines.push(`-- destructive: ${destructiveChange}`);
+	if (plan.statements.length > 0) {
+		lines.push("");
+		for (const statement of plan.statements) lines.push(statement);
+	} else {
+		lines.push("");
+		lines.push("-- no-op");
+	}
+	return `${lines.join("\n")}\n`;
+}
+function parseSchemaSnapshot(source) {
+	const parsed = JSON.parse(source);
+	if (parsed.version !== 1 || !Array.isArray(parsed.tables) || typeof parsed.hash !== "string") throw new Error("Invalid schema snapshot file.");
+	return parsed;
+}
+function renderCreateTableStatement(tableName) {
+	return `
+CREATE TABLE IF NOT EXISTS ${quoteIdentifier(tableName)} (
+  _id TEXT PRIMARY KEY,
+  _creationTime INTEGER NOT NULL,
+  _json TEXT NOT NULL
+);`.trim();
+}
+function renderCreateIndexStatement(tableName, indexName, fields) {
+	const expressions = fields.map((field) => `json_extract(_json, '$.${field}')`).join(", ");
+	return `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(`idx_${tableName}_${indexName}`)} ON ${quoteIdentifier(tableName)} (${expressions});`;
+}
+function renderCreateSearchIndexStatement(tableName, searchIndex) {
+	return `CREATE VIRTUAL TABLE IF NOT EXISTS ${quoteIdentifier(searchIndexTableName(tableName, searchIndex.name))} USING fts5(_id UNINDEXED, search_value);`;
+}
+function searchIndexTableName(tableName, indexName) {
+	return `fts_${tableName}_${indexName}`;
+}
+function createSchemaHash(value) {
+	return stableStringify(value);
+}
+function quoteIdentifier(identifier) {
+	return `"${identifier.replaceAll("\"", "\"\"")}"`;
+}
+function stableStringify(value) {
+	return JSON.stringify(sortValue(value));
+}
+function sortValue(value) {
+	if (Array.isArray(value)) return value.map(sortValue);
+	if (value && typeof value === "object") return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, nested]) => [key, sortValue(nested)]));
+	return value;
+}
+//#endregion
+export { createSchemaSnapshot, diffSchemaSnapshots, parseSchemaSnapshot, renderCreateIndexStatement, renderCreateSearchIndexStatement, renderCreateTableStatement, renderMigrationSql, searchIndexTableName };
+
+//# sourceMappingURL=planner.js.map

package/dist/schema/src/planner.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"planner.js","names":[],"sources":["../../../../schema/src/planner.ts"],"sourcesContent":["import {\r\n  type SearchIndexDefinition,\r\n  type SyncoreSchemaDefinition,\r\n  type SyncoreSchema\r\n} from \"./definition.js\";\r\nimport {\r\n  describeValidator,\r\n  type ValidatorDescription\r\n} from \"./validators.js\";\r\n\r\nexport interface TableSnapshot {\r\n  name: string;\r\n  validator: ValidatorDescription;\r\n  indexes: Array<{\r\n    name: string;\r\n    fields: string[];\r\n  }>;\r\n  searchIndexes: Array<{\r\n    name: string;\r\n    searchField: string;\r\n    filterFields: string[];\r\n  }>;\r\n}\r\n\r\nexport interface SchemaSnapshot {\r\n  version: 1;\r\n  tables: TableSnapshot[];\r\n  hash: string;\r\n}\r\n\r\nexport interface SchemaMigrationPlan {\r\n  previousHash: string | null;\r\n  nextHash: string;\r\n  statements: string[];\r\n  warnings: string[];\r\n  destructiveChanges: string[];\r\n}\r\n\r\nexport function createSchemaSnapshot<TTables extends SyncoreSchemaDefinition>(\r\n  schema: SyncoreSchema<TTables>\r\n): SchemaSnapshot {\r\n  const tables = schema\r\n    .tableNames()\r\n    .sort((left, right) => left.localeCompare(right))\r\n    .map((tableName) => {\r\n      const table = schema.getTable(tableName);\r\n      return {\r\n        name: tableName,\r\n        validator: describeValidator(table.validator),\r\n        indexes: table.indexes\r\n          .map((index) => ({\r\n            name: index.name,\r\n            fields: [...index.fields]\r\n          }))\r\n          .sort((left, right) => left.name.localeCompare(right.name)),\r\n        searchIndexes: table.searchIndexes\r\n          .map((index) => ({\r\n            name: index.name,\r\n            searchField: index.searchField,\r\n            filterFields: [...index.filterFields]\r\n          }))\r\n          .sort((left, right) => left.name.localeCompare(right.name))\r\n      };\r\n    });\r\n\r\n  const base = {\r\n    version: 1 as const,\r\n    tables\r\n  };\r\n\r\n  return {\r\n    ...base,\r\n    hash: createSchemaHash(base)\r\n  };\r\n}\r\n\r\nexport function diffSchemaSnapshots(\r\n  previousSnapshot: SchemaSnapshot | null | undefined,\r\n  nextSnapshot: SchemaSnapshot\r\n): SchemaMigrationPlan {\r\n  const statements: string[] = [];\r\n  const warnings: string[] = [];\r\n  const destructiveChanges: string[] = [];\r\n\r\n  const previousTables = new Map(\r\n    (previousSnapshot?.tables ?? []).map((table) => [table.name, table])\r\n  );\r\n  const nextTables = new Map(nextSnapshot.tables.map((table) => [table.name, table]));\r\n\r\n  for (const table of nextSnapshot.tables) {\r\n    const previousTable = previousTables.get(table.name);\r\n    if (!previousTable) {\r\n      statements.push(renderCreateTableStatement(table.name));\r\n      for (const index of table.indexes) {\r\n        statements.push(renderCreateIndexStatement(table.name, index.name, index.fields));\r\n      }\r\n      for (const searchIndex of table.searchIndexes) {\r\n        statements.push(renderCreateSearchIndexStatement(table.name, searchIndex));\r\n      }\r\n      continue;\r\n    }\r\n\r\n    if (stableStringify(previousTable.validator) !== stableStringify(table.validator)) {\r\n      warnings.push(\r\n        `Validator changed for table \"${table.name}\". Existing rows are not rewritten automatically.`\r\n      );\r\n    }\r\n\r\n    const previousIndexes = new Map(\r\n      previousTable.indexes.map((index) => [index.name, index])\r\n    );\r\n    const nextIndexes = new Map(table.indexes.map((index) => [index.name, index]));\r\n\r\n    for (const index of table.indexes) {\r\n      const previousIndex = previousIndexes.get(index.name);\r\n      if (!previousIndex) {\r\n        statements.push(renderCreateIndexStatement(table.name, index.name, index.fields));\r\n        continue;\r\n      }\r\n      if (stableStringify(previousIndex.fields) !== stableStringify(index.fields)) {\r\n        destructiveChanges.push(\r\n          `Index \"${table.name}.${index.name}\" changed fields and requires a manual migration.`\r\n        );\r\n      }\r\n    }\r\n\r\n    for (const previousIndex of previousTable.indexes) {\r\n      if (!nextIndexes.has(previousIndex.name)) {\r\n        destructiveChanges.push(\r\n          `Index \"${table.name}.${previousIndex.name}\" was removed and requires a manual migration.`\r\n        );\r\n      }\r\n    }\r\n\r\n    const previousSearchIndexes = new Map(\r\n      previousTable.searchIndexes.map((index) => [index.name, index])\r\n    );\r\n    const nextSearchIndexes = new Map(\r\n      table.searchIndexes.map((index) => [index.name, index])\r\n    );\r\n\r\n    for (const searchIndex of table.searchIndexes) {\r\n      const previousSearchIndex = previousSearchIndexes.get(searchIndex.name);\r\n      if (!previousSearchIndex) {\r\n        statements.push(renderCreateSearchIndexStatement(table.name, searchIndex));\r\n        continue;\r\n      }\r\n      if (stableStringify(previousSearchIndex) !== stableStringify(searchIndex)) {\r\n        destructiveChanges.push(\r\n          `Search index \"${table.name}.${searchIndex.name}\" changed and requires a manual migration.`\r\n        );\r\n      }\r\n    }\r\n\r\n    for (const previousSearchIndex of previousTable.searchIndexes) {\r\n      if (!nextSearchIndexes.has(previousSearchIndex.name)) {\r\n        destructiveChanges.push(\r\n          `Search index \"${table.name}.${previousSearchIndex.name}\" was removed and requires a manual migration.`\r\n        );\r\n      }\r\n    }\r\n  }\r\n\r\n  for (const previousTable of previousSnapshot?.tables ?? []) {\r\n    if (!nextTables.has(previousTable.name)) {\r\n      destructiveChanges.push(\r\n        `Table \"${previousTable.name}\" was removed and requires a manual migration.`\r\n      );\r\n    }\r\n  }\r\n\r\n  return {\r\n    previousHash: previousSnapshot?.hash ?? null,\r\n    nextHash: nextSnapshot.hash,\r\n    statements,\r\n    warnings,\r\n    destructiveChanges\r\n  };\r\n}\r\n\r\nexport function renderMigrationSql(\r\n  plan: SchemaMigrationPlan,\r\n  options?: { title?: string }\r\n): string {\r\n  const lines: string[] = [];\r\n\r\n  lines.push(`-- ${options?.title ?? \"Syncore migration\"}`);\r\n  lines.push(`-- previous: ${plan.previousHash ?? \"none\"}`);\r\n  lines.push(`-- next: ${plan.nextHash}`);\r\n\r\n  for (const warning of plan.warnings) {\r\n    lines.push(`-- warning: ${warning}`);\r\n  }\r\n\r\n  if (plan.destructiveChanges.length > 0) {\r\n    for (const destructiveChange of plan.destructiveChanges) {\r\n      lines.push(`-- destructive: ${destructiveChange}`);\r\n    }\r\n  }\r\n\r\n  if (plan.statements.length > 0) {\r\n    lines.push(\"\");\r\n    for (const statement of plan.statements) {\r\n      lines.push(statement);\r\n    }\r\n  } else {\r\n    lines.push(\"\");\r\n    lines.push(\"-- no-op\");\r\n  }\r\n\r\n  return `${lines.join(\"\\n\")}\\n`;\r\n}\r\n\r\nexport function parseSchemaSnapshot(source: string): SchemaSnapshot {\r\n  const parsed = JSON.parse(source) as SchemaSnapshot;\r\n  if (parsed.version !== 1 || !Array.isArray(parsed.tables) || typeof parsed.hash !== \"string\") {\r\n    throw new Error(\"Invalid schema snapshot file.\");\r\n  }\r\n  return parsed;\r\n}\r\n\r\nexport function renderCreateTableStatement(tableName: string): string {\r\n  return `\r\nCREATE TABLE IF NOT EXISTS ${quoteIdentifier(tableName)} (\r\n  _id TEXT PRIMARY KEY,\r\n  _creationTime INTEGER NOT NULL,\r\n  _json TEXT NOT NULL\r\n);`.trim();\r\n}\r\n\r\nexport function renderCreateIndexStatement(\r\n  tableName: string,\r\n  indexName: string,\r\n  fields: string[]\r\n): string {\r\n  const expressions = fields\r\n    .map((field) => `json_extract(_json, '$.${field}')`)\r\n    .join(\", \");\r\n  return `CREATE INDEX IF NOT EXISTS ${quoteIdentifier(\r\n    `idx_${tableName}_${indexName}`\r\n  )} ON ${quoteIdentifier(tableName)} (${expressions});`;\r\n}\r\n\r\nexport function renderCreateSearchIndexStatement(\r\n  tableName: string,\r\n  searchIndex: SearchIndexDefinition | TableSnapshot[\"searchIndexes\"][number]\r\n): string {\r\n  return `CREATE VIRTUAL TABLE IF NOT EXISTS ${quoteIdentifier(\r\n    searchIndexTableName(tableName, searchIndex.name)\r\n  )} USING fts5(_id UNINDEXED, search_value);`;\r\n}\r\n\r\nexport function searchIndexTableName(tableName: string, indexName: string): string {\r\n  return `fts_${tableName}_${indexName}`;\r\n}\r\n\r\nfunction createSchemaHash(value: Omit<SchemaSnapshot, \"hash\">): string {\r\n  return stableStringify(value);\r\n}\r\n\r\nfunction quoteIdentifier(identifier: string): string {\r\n  return `\"${identifier.replaceAll('\"', '\"\"')}\"`;\r\n}\r\n\r\nfunction stableStringify(value: unknown): string {\r\n  return JSON.stringify(sortValue(value));\r\n}\r\n\r\nfunction sortValue(value: unknown): unknown {\r\n  if (Array.isArray(value)) {\r\n    return value.map(sortValue);\r\n  }\r\n  if (value && typeof value === \"object\") {\r\n    return Object.fromEntries(\r\n      Object.entries(value as Record<string, unknown>)\r\n        .sort(([left], [right]) => left.localeCompare(right))\r\n        .map(([key, nested]) => [key, sortValue(nested)])\r\n    );\r\n  }\r\n  return value;\r\n}\r\n"],"mappings":"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"}

package/dist/schema/src/validators.d.ts

@@ -0,0 +1,194 @@
+//#region ../schema/src/validators.d.ts
+type ValidatorKind = "string" | "number" | "boolean" | "literal" | "array" | "object" | "id" | "optional" | "any" | "null";
+/**
+ * Validates unknown input at runtime and carries its parsed TypeScript type.
+ *
+ * Syncore uses validators for function arguments, return values, and table
+ * definitions. Most apps create validators through {@link v} instead of
+ * instantiating validator classes directly.
+ */
+interface Validator<TValue> {
+  readonly kind: ValidatorKind;
+  /**
+   * Parse and validate an unknown value.
+   *
+   * @param value - The value to validate.
+   * @param path - A human-readable path used in validation errors.
+   * @returns The parsed value when validation succeeds.
+   */
+  parse(value: unknown, path?: string): TValue;
+}
+type ValidatorDescription = {
+  kind: "string";
+} | {
+  kind: "number";
+} | {
+  kind: "boolean";
+} | {
+  kind: "null";
+} | {
+  kind: "any";
+} | {
+  kind: "literal";
+  value: string | number | boolean | null;
+} | {
+  kind: "array";
+  item: ValidatorDescription;
+} | {
+  kind: "object";
+  shape: Record<string, ValidatorDescription>;
+} | {
+  kind: "id";
+  tableName: string;
+} | {
+  kind: "optional";
+  inner: ValidatorDescription;
+};
+interface ObjectValidatorShape {
+  [key: string]: Validator<unknown>;
+}
+declare class StringValidator implements Validator<string> {
+  readonly kind: "string";
+  parse(value: unknown, path?: string): string;
+}
+declare class NumberValidator implements Validator<number> {
+  readonly kind: "number";
+  parse(value: unknown, path?: string): number;
+}
+declare class BooleanValidator implements Validator<boolean> {
+  readonly kind: "boolean";
+  parse(value: unknown, path?: string): boolean;
+}
+declare class NullValidator implements Validator<null> {
+  readonly kind: "null";
+  parse(value: unknown, path?: string): null;
+}
+declare class AnyValidator implements Validator<unknown> {
+  readonly kind: "any";
+  parse(value: unknown): unknown;
+}
+declare class LiteralValidator<TValue extends string | number | boolean | null> implements Validator<TValue> {
+  readonly literalValue: TValue;
+  readonly kind: "literal";
+  constructor(literalValue: TValue);
+  parse(value: unknown, path?: string): TValue;
+}
+declare class ArrayValidator<TItem> implements Validator<TItem[]> {
+  readonly itemValidator: Validator<TItem>;
+  readonly kind: "array";
+  constructor(itemValidator: Validator<TItem>);
+  parse(value: unknown, path?: string): TItem[];
+}
+declare class ObjectValidator<TShape extends ObjectValidatorShape> implements Validator<{ [TKey in keyof TShape]: Infer<TShape[TKey]> }> {
+  readonly shape: TShape;
+  readonly kind: "object";
+  constructor(shape: TShape);
+  parse(value: unknown, path?: string): { [TKey in keyof TShape]: Infer<TShape[TKey]> };
+}
+declare class IdValidator<TTableName extends string> implements Validator<string> {
+  readonly tableName: TTableName;
+  readonly kind: "id";
+  constructor(tableName: TTableName);
+  parse(value: unknown, path?: string): string;
+}
+declare class OptionalValidator<TValue> implements Validator<TValue | undefined> {
+  readonly inner: Validator<TValue>;
+  readonly kind: "optional";
+  constructor(inner: Validator<TValue>);
+  parse(value: unknown, path?: string): TValue | undefined;
+}
+type Infer<TValidator> = TValidator extends Validator<infer TValue> ? TValue : never;
+type ValidatorMap = Record<string, Validator<unknown>>;
+/**
+ * The public validator builder API.
+ *
+ * Hover each property in your editor to see what it validates and how to use it.
+ */
+interface ValidatorBuilderApi {
+  /**
+   * Validate a string value.
+   *
+   * @returns A validator that accepts JavaScript strings.
+   */
+  string(): StringValidator;
+  /**
+   * Validate a number value.
+   *
+   * @returns A validator that accepts finite JavaScript numbers.
+   */
+  number(): NumberValidator;
+  /**
+   * Validate a boolean value.
+   *
+   * @returns A validator that accepts `true` and `false`.
+   */
+  boolean(): BooleanValidator;
+  /**
+   * Validate the literal value `null`.
+   *
+   * @returns A validator that only accepts `null`.
+   */
+  null(): NullValidator;
+  /**
+   * Accept any value without validation.
+   *
+   * Use this sparingly for escape hatches when you do not want Syncore to
+   * enforce a more specific runtime shape.
+   */
+  any(): AnyValidator;
+  /**
+   * Validate a single literal value.
+   *
+   * @param literalValue - The exact value that must be provided.
+   * @returns A validator that only accepts that one value.
+   */
+  literal<TValue extends string | number | boolean | null>(literalValue: TValue): LiteralValidator<TValue>;
+  /**
+   * Validate an array whose items all use the same validator.
+   *
+   * @param itemValidator - The validator for each item in the array.
+   * @returns A validator for arrays of the provided item type.
+   */
+  array<TItem>(itemValidator: Validator<TItem>): ArrayValidator<TItem>;
+  /**
+   * Validate an object with a fixed property shape.
+   *
+   * @param shape - The validators for each property on the object.
+   * @returns A validator for objects matching that shape.
+   */
+  object<TShape extends ObjectValidatorShape>(shape: TShape): ObjectValidator<TShape>;
+  /**
+   * Validate an identifier string that points at a table.
+   *
+   * Use this for document ids that come from Syncore tables.
+   *
+   * @param tableName - The name of the referenced table.
+   * @returns A validator for ids belonging to that table.
+   */
+  id<TTableName extends string>(tableName: TTableName): IdValidator<TTableName>;
+  /**
+   * Make another validator optional.
+   *
+   * @param inner - The validator for the defined case.
+   * @returns A validator that accepts `undefined` or the inner value.
+   */
+  optional<TValue>(inner: Validator<TValue>): OptionalValidator<TValue>;
+}
+declare function ensureObjectValidator(value: Validator<unknown> | ValidatorMap): Validator<unknown>;
+/**
+ * Build runtime validators for schemas, function args, and return values.
+ *
+ * @example
+ * ```ts
+ * defineTable({
+ *   text: v.string(),
+ *   done: v.boolean(),
+ *   ownerId: v.optional(v.id("users"))
+ * });
+ * ```
+ */
+declare const v: ValidatorBuilderApi;
+declare function describeValidator(validator: Validator<unknown>): ValidatorDescription;
+//#endregion
+export { AnyValidator, ArrayValidator, BooleanValidator, IdValidator, Infer, LiteralValidator, NullValidator, NumberValidator, ObjectValidator, ObjectValidatorShape, OptionalValidator, StringValidator, Validator, ValidatorBuilderApi, ValidatorDescription, ValidatorKind, ValidatorMap, describeValidator, ensureObjectValidator, v };
+//# sourceMappingURL=validators.d.ts.map

package/dist/schema/src/validators.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"validators.d.ts","names":[],"sources":["../../../../schema/src/validators.ts"],"mappings":"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"}