kindstore 0.0.0 → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) Alec Larson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,59 @@
+# kindstore
+
+kindstore is a registry-driven document store for Bun and SQLite. You define
+document kinds with Zod, declare which top-level fields are queryable, and keep
+payload and schema migrations explicit.
+
+Requires Bun at runtime because kindstore uses `bun:sqlite`.
+
+```sh
+bun add kindstore zod
+```
+
+```ts
+import { z } from "zod";
+import { kind, kindstore } from "kindstore";
+
+const Post = z.object({
+  authorId: z.string(),
+  slug: z.string(),
+  title: z.string(),
+  status: z.enum(["draft", "published"]),
+  updatedAt: z.number().int(),
+});
+
+const db = kindstore({
+  connection: { filename: ":memory:" },
+  posts: kind("pst", Post)
+    .updatedAt("updatedAt")
+    .index("authorId")
+    .index("slug")
+    .index("status")
+    .index("updatedAt", { type: "integer" }),
+});
+
+const id = db.posts.newId();
+
+db.posts.put(id, {
+  authorId: "usr_1",
+  slug: "hello-kindstore",
+  title: "Hello, kindstore",
+  status: "published",
+});
+
+const publishedPosts = db.posts.findMany({
+  where: { status: "published" },
+  orderBy: { updatedAt: "desc" },
+});
+
+const firstPage = db.posts.findPage({
+  where: { status: "published" },
+  orderBy: { updatedAt: "desc" },
+  limit: 20,
+});
+```
+
+Next:
+
+- Start with the intermediate guides in [docs/course/README.md](./docs/course/README.md)
+- Read the maintainer-facing system docs in [docs/architecture-overview.md](./docs/architecture-overview.md)

package/dist/index.d.mts

@@ -0,0 +1,164 @@
+import { Database } from "bun:sqlite";
+import { z } from "zod";
+
+//#region src/types.d.ts
+type SqliteTypeHint = "text" | "integer" | "real" | "numeric";
+type IndexDirection = "asc" | "desc";
+type TaggedId<Tag extends string> = `${Tag}_${string}` & {
+  readonly __kindstoreTag?: Tag;
+};
+type KindDefinitionBag = {
+  tag: string;
+  schema: z.ZodObject<any>;
+  indexed: string;
+  createdAt: string;
+  updatedAt: string;
+  version: number;
+};
+type KindValue<T extends KindDefinitionBag> = z.output<T["schema"]>;
+type KindManagedTimestampField<T extends KindDefinitionBag> = Extract<T["createdAt"] | T["updatedAt"], keyof KindValue<T> & string>;
+type KindInputValue<T extends KindDefinitionBag> = Omit<KindValue<T>, KindManagedTimestampField<T>> & Partial<Pick<KindValue<T>, KindManagedTimestampField<T>>>;
+type KindId<T extends KindDefinitionBag> = TaggedId<T["tag"]>;
+type KindIndexedField<T extends KindDefinitionBag> = Extract<T["indexed"], keyof KindValue<T> & string>;
+type FilterOperators<T> = {
+  in?: readonly Exclude<T, undefined>[];
+  gt?: Exclude<T, undefined>;
+  gte?: Exclude<T, undefined>;
+  lt?: Exclude<T, undefined>;
+  lte?: Exclude<T, undefined>;
+};
+type WhereOperand<T> = Exclude<T, undefined> | null | FilterOperators<T>;
+type KindWhere<T extends KindDefinitionBag> = Partial<{ [K in KindIndexedField<T>]: WhereOperand<KindValue<T>[K]> }>;
+type KindOrderBy<T extends KindDefinitionBag> = Partial<Record<KindIndexedField<T>, IndexDirection>>;
+type FindManyOptions<T extends KindDefinitionBag> = {
+  where?: KindWhere<T>;
+  orderBy?: KindOrderBy<T>;
+  limit?: number;
+};
+type KindPageCursor<T extends KindDefinitionBag> = string & {
+  readonly __kindstorePageCursor?: T["tag"];
+};
+type FindPageOptions<T extends KindDefinitionBag> = {
+  where?: KindWhere<T>;
+  orderBy: KindOrderBy<T>;
+  limit: number;
+  after?: KindPageCursor<T>;
+};
+type FindPageResult<T extends KindDefinitionBag> = {
+  items: KindValue<T>[];
+  next?: KindPageCursor<T>;
+};
+type PatchValue<T> = T extends object ? Partial<T> : never;
+type KindMigrationContext = {
+  readonly now: number;
+};
+type KindMigration<T extends object> = (value: Partial<T> & Record<string, unknown>, context: KindMigrationContext) => T | Record<string, unknown>;
+type MetadataDefinitionMap = Record<string, z.ZodTypeAny>;
+interface SchemaMigrationPlanner {
+  rename(previousKindKey: string, nextKindKey: string): this;
+  drop(previousKindKey: string): this;
+  retag(kindKey: string, previousTag: string): this;
+}
+type SchemaDefinition = {
+  migrate(planner: SchemaMigrationPlanner): void;
+};
+type MetadataValue<T extends MetadataDefinitionMap, K extends keyof T & string> = z.output<T[K]>;
+type KindRegistry = Record<string, KindDefinition<any>>;
+type ConnectionConfig = {
+  filename: string;
+  options?: ConstructorParameters<typeof Database>[1];
+};
+//#endregion
+//#region src/kind.d.ts
+type MultiIndexFields<T extends KindDefinitionBag> = { [K in keyof KindValue<T> & string]?: IndexDirection };
+type IndexDefinition = {
+  field: string;
+  type?: SqliteTypeHint;
+  single: boolean;
+};
+type MultiIndexDefinition = {
+  name: string;
+  fields: readonly [string, IndexDirection][];
+};
+declare class KindDefinition<T extends KindDefinitionBag> {
+  readonly tag: T["tag"];
+  readonly schema: T["schema"];
+  version: T["version"];
+  createdAtField?: T["createdAt"];
+  updatedAtField?: T["updatedAt"];
+  readonly indexes: Map<string, IndexDefinition>;
+  readonly multiIndexes: MultiIndexDefinition[];
+  migrations?: Record<number, KindMigration<KindValue<T>>>;
+  constructor(tag: T["tag"], schema: T["schema"], version: T["version"]);
+  index<TKey extends keyof KindValue<T> & string>(field: TKey, options?: {
+    type?: SqliteTypeHint;
+  }): KindDefinition<Omit<T, "indexed"> & {
+    indexed: T["indexed"] | TKey;
+  }>;
+  createdAt<TKey extends keyof KindValue<T> & string>(field: TKey): KindDefinition<Omit<T, "createdAt"> & {
+    createdAt: TKey;
+  }>;
+  updatedAt<TKey extends keyof KindValue<T> & string>(field: TKey): KindDefinition<Omit<T, "updatedAt"> & {
+    updatedAt: TKey;
+  }>;
+  multi<const TName extends string, const TFields extends MultiIndexFields<T> & Record<string, IndexDirection>>(name: TName, fields: TFields): KindDefinition<Omit<T, "indexed"> & {
+    indexed: T["indexed"] | (keyof TFields & string);
+  }>;
+  migrate<const TVersion extends number>(version: TVersion, steps: Record<number, KindMigration<KindValue<T>>>): KindDefinition<Omit<T, "version"> & {
+    version: TVersion;
+  }>;
+}
+declare function kind<const TTag extends string, const TSchema extends z.ZodObject<any>>(tag: TTag, schema: TSchema): KindDefinition<{
+  tag: TTag;
+  schema: TSchema;
+  indexed: never;
+  createdAt: never;
+  updatedAt: never;
+  version: 1;
+}>;
+//#endregion
+//#region src/runtime.d.ts
+type KindCollectionSurface<T extends KindDefinitionBag> = {
+  newId(): KindId<T>;
+  get(id: KindId<T>): KindValue<T> | undefined;
+  put(id: KindId<T>, value: KindInputValue<T>): KindValue<T>;
+  delete(id: KindId<T>): boolean;
+  update(id: KindId<T>, updater: PatchValue<KindInputValue<T>> | ((current: KindValue<T>) => KindInputValue<T>)): KindValue<T> | undefined;
+  first(options?: FindManyOptions<T>): KindValue<T> | undefined;
+  findMany(options?: FindManyOptions<T>): KindValue<T>[];
+  findPage(options: FindPageOptions<T>): FindPageResult<T>;
+  iterate(options?: FindManyOptions<T>): IterableIterator<KindValue<T>>;
+};
+type MetadataSurface<T extends MetadataDefinitionMap> = {
+  get<K extends keyof T & string>(key: K): MetadataValue<T, K> | undefined;
+  set<K extends keyof T & string>(key: K, value: MetadataValue<T, K>): MetadataValue<T, K>;
+  delete<K extends keyof T & string>(key: K): boolean;
+  update<K extends keyof T & string>(key: K, updater: (current: MetadataValue<T, K> | undefined) => MetadataValue<T, K>): MetadataValue<T, K>;
+};
+type KindStoreSurface<TKinds extends KindRegistry, TMetadata extends MetadataDefinitionMap> = {
+  readonly raw: Database;
+  readonly metadata: MetadataSurface<TMetadata>;
+  batch<TResult>(callback: () => TResult): TResult;
+  close(): void;
+} & { [K in keyof TKinds]: TKinds[K] extends KindDefinition<infer TBag> ? KindCollectionSurface<TBag> : never };
+type PublicKindCollection<T extends KindDefinitionBag> = KindCollectionSurface<T>;
+type PublicMetadataCollection<T extends MetadataDefinitionMap> = MetadataSurface<T>;
+type PublicKindstore<TKinds extends KindRegistry, TMetadata extends MetadataDefinitionMap> = KindStoreSurface<TKinds, TMetadata>;
+//#endregion
+//#region src/store.d.ts
+type AnyStoreInput = {
+  connection: ConnectionConfig;
+  metadata?: MetadataDefinitionMap;
+  schema?: SchemaDefinition;
+} & Record<string, unknown>;
+type InferKinds<TInput extends AnyStoreInput> = { [K in keyof TInput as K extends "connection" | "metadata" | "schema" ? never : TInput[K] extends KindDefinition<any> ? K : never]: Extract<TInput[K], KindDefinition<any>> };
+type InferMetadata<TInput extends AnyStoreInput> = TInput extends {
+  metadata: infer TMetadata extends MetadataDefinitionMap;
+} ? TMetadata : {};
+type KindCollection<T extends KindDefinitionBag> = PublicKindCollection<T>;
+type MetadataCollection<T extends MetadataDefinitionMap> = PublicMetadataCollection<T>;
+type Kindstore<TKinds extends KindRegistry, TMetadata extends MetadataDefinitionMap = {}> = PublicKindstore<TKinds, TMetadata>;
+declare function kindstore<const TInput extends AnyStoreInput>(input: TInput): Kindstore<InferKinds<TInput>, InferMetadata<TInput>>;
+type MetadataSchemas = Record<string, z.ZodTypeAny>;
+//#endregion
+export { type ConnectionConfig, type FilterOperators, type FindManyOptions, type FindPageOptions, type FindPageResult, type IndexDirection, type KindCollection, KindDefinition, type KindDefinitionBag, type KindId, type KindIndexedField, type KindInputValue, type KindMigration, type KindMigrationContext, type KindOrderBy, type KindPageCursor, type KindRegistry, type KindValue, type KindWhere, type Kindstore, type MetadataCollection, type MetadataDefinitionMap, type MetadataSchemas, type MetadataValue, type PatchValue, type SchemaDefinition, type SchemaMigrationPlanner, type SqliteTypeHint, type TaggedId, type WhereOperand, kind, kindstore };

package/dist/index.mjs

@@ -0,0 +1,910 @@
+import { Database } from "bun:sqlite";
+import { monotonicFactory } from "ulid";
+//#region src/kind.ts
+var KindDefinition = class {
+	tag;
+	schema;
+	version;
+	createdAtField;
+	updatedAtField;
+	indexes = /* @__PURE__ */ new Map();
+	multiIndexes = [];
+	migrations;
+	constructor(tag, schema, version) {
+		this.tag = tag;
+		this.schema = schema;
+		this.version = version;
+	}
+	index(field, options = {}) {
+		const current = this.indexes.get(field);
+		this.indexes.set(field, {
+			field,
+			single: true,
+			type: options.type ?? current?.type
+		});
+		return this;
+	}
+	createdAt(field) {
+		if (field === this.updatedAtField) throw new Error(`Kind "${this.tag}" cannot use "${field}" for both createdAt and updatedAt.`);
+		this.createdAtField = field;
+		return this;
+	}
+	updatedAt(field) {
+		if (field === this.createdAtField) throw new Error(`Kind "${this.tag}" cannot use "${field}" for both createdAt and updatedAt.`);
+		this.updatedAtField = field;
+		return this;
+	}
+	multi(name, fields) {
+		const entries = Object.entries(fields);
+		if (!entries.length) throw new Error(`Multi-index "${name}" must include at least one field.`);
+		this.multiIndexes.push({
+			name,
+			fields: entries
+		});
+		return this;
+	}
+	migrate(version, steps) {
+		if (!Number.isInteger(version) || version < 1) throw new Error(`Kind "${this.tag}" version must be a positive integer.`);
+		this.version = version;
+		this.migrations = steps;
+		return this;
+	}
+};
+function kind(tag, schema) {
+	return new KindDefinition(tag, schema, 1);
+}
+//#endregion
+//#region src/util.ts
+function isFilterOperators(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value) && ("in" in value || "gt" in value || "gte" in value || "lt" in value || "lte" in value);
+}
+function assertTaggedId(tag, id) {
+	if (!id.startsWith(`${tag}_`)) throw new Error(`Expected ID for tag "${tag}", received "${id}".`);
+}
+function parsePayload(payload) {
+	return JSON.parse(payload);
+}
+function columnExpression(type, field) {
+	const extract = `json_extract("payload", '${`$."${field.replaceAll("\"", "\"\"")}"`}')`;
+	return type === "text" ? extract : `CAST(${extract} AS ${type.toUpperCase()})`;
+}
+function indexName(table, suffix) {
+	return `idx_${table}_${suffix}`;
+}
+function sameColumns(left, right) {
+	return left.length === right.length && left.every((value, index) => value === right[index]);
+}
+function isRecord(value) {
+	return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function isSqliteTypeHint(value) {
+	return value === "text" || value === "integer" || value === "real" || value === "numeric";
+}
+function quoteIdentifier(value) {
+	return `"${value.replaceAll("\"", "\"\"")}"`;
+}
+function quoteString(value) {
+	return `'${value.replaceAll("'", "''")}'`;
+}
+function snakeCase(value) {
+	let result = "";
+	for (let index = 0; index < value.length; index++) {
+		const char = value[index];
+		const lower = char.toLowerCase();
+		if (index && char !== lower && value[index - 1] !== "_") result += "_";
+		result += lower;
+	}
+	return result;
+}
+//#endregion
+//#region src/runtime.ts
+const KINDSTORE_FORMAT_VERSION = 2;
+const INTERNAL_TABLE = "__kindstore_internal";
+const APP_METADATA_TABLE = "__kindstore_app_metadata";
+const LEGACY_KIND_VERSIONS_TABLE = "__kindstore_kind_versions";
+const LEGACY_APP_METADATA_TABLE = "__kindstore_metadata";
+const STORE_FORMAT_VERSION_KEY = "store_format_version";
+const KIND_VERSIONS_KEY = "kind_versions";
+const SCHEMA_SNAPSHOT_KEY = "schema_snapshot";
+const RESERVED_STORE_KEYS = new Set([
+	"batch",
+	"close",
+	"connection",
+	"metadata",
+	"raw"
+]);
+const RESERVED_COLUMN_NAMES = new Set(["id", "payload"]);
+const nextUlid = monotonicFactory();
+const PAGE_CURSOR_VERSION = 1;
+function createStore(connection, kinds, metadataDefinitions, schemaDefinition) {
+	const database = new Database(connection.filename, connection.options);
+	try {
+		return new KindstoreRuntime(database, normalizeKinds(kinds), metadataDefinitions, normalizeSchemaPlan(schemaDefinition)).publicStore;
+	} catch (error) {
+		database.close();
+		throw error;
+	}
+}
+var KindstoreRuntime = class {
+	database;
+	kinds;
+	publicStore;
+	internal;
+	metadata;
+	schemaPlan;
+	constructor(database, kinds, metadataDefinitions, schemaPlan) {
+		this.database = database;
+		this.kinds = kinds;
+		this.schemaPlan = schemaPlan;
+		this.publicStore = this;
+		this.ensureInternalTable();
+		this.internal = new InternalMetadataRuntime(database);
+		this.bootstrap();
+		this.metadata = new MetadataRuntime(database, metadataDefinitions);
+		this.publicStore.raw = database;
+		this.publicStore.metadata = this.metadata;
+		for (const [key, definition] of kinds) this.publicStore[key] = new KindCollectionRuntime(database, definition);
+	}
+	batch(callback) {
+		return this.database.transaction(callback)();
+	}
+	close() {
+		this.database.close();
+	}
+	bootstrap() {
+		this.database.transaction(() => {
+			this.ensureStoreFormatVersion();
+			this.database.run(`CREATE TABLE IF NOT EXISTS ${quoteIdentifier(APP_METADATA_TABLE)} (
+          "key" TEXT PRIMARY KEY NOT NULL,
+          "payload" TEXT NOT NULL,
+          "created_at" INTEGER NOT NULL,
+          "updated_at" INTEGER NOT NULL
+        ) STRICT`);
+			const previousSnapshot = this.applySchemaMigrations(this.internal.getSchemaSnapshot());
+			for (const definition of this.kinds.values()) {
+				this.ensureKindTable(definition);
+				this.ensureGeneratedColumns(definition);
+				this.reconcileIndexes(definition, previousSnapshot?.kinds[definition.key]);
+				this.dropStaleGeneratedColumns(definition, previousSnapshot?.kinds[definition.key]);
+				this.migrateKind(definition);
+			}
+			this.internal.setSchemaSnapshot(this.createSchemaSnapshot());
+		})();
+	}
+	ensureInternalTable() {
+		this.database.run(`CREATE TABLE IF NOT EXISTS ${quoteIdentifier(INTERNAL_TABLE)} (
+        "key" TEXT PRIMARY KEY NOT NULL,
+        "payload" TEXT NOT NULL,
+        "updated_at" INTEGER NOT NULL
+      ) STRICT`);
+	}
+	ensureStoreFormatVersion() {
+		const version = this.internal.getNumber(STORE_FORMAT_VERSION_KEY);
+		if (version == null) {
+			if (this.hasExistingStoreArtifacts()) throw new Error("Store is missing the kindstore format version and cannot be opened safely.");
+			this.internal.set(STORE_FORMAT_VERSION_KEY, KINDSTORE_FORMAT_VERSION);
+			return;
+		}
+		if (!Number.isInteger(version) || version < 1) throw new Error(`Invalid kindstore format version "${version}".`);
+		if (version > KINDSTORE_FORMAT_VERSION) throw new Error(`Store format version ${version} is newer than supported version ${KINDSTORE_FORMAT_VERSION}.`);
+		if (version < KINDSTORE_FORMAT_VERSION) {
+			this.migrateStoreFormat(version);
+			this.internal.set(STORE_FORMAT_VERSION_KEY, KINDSTORE_FORMAT_VERSION);
+		}
+	}
+	migrateStoreFormat(version) {
+		for (let currentVersion = version; currentVersion < KINDSTORE_FORMAT_VERSION; currentVersion++) switch (currentVersion) {
+			case 1:
+				this.migrateStoreFormat1To2();
+				break;
+			default: throw new Error(`Store format version ${currentVersion} cannot be upgraded to ${KINDSTORE_FORMAT_VERSION}.`);
+		}
+	}
+	migrateStoreFormat1To2() {
+		const tables = /* @__PURE__ */ new Set();
+		const snapshot = this.internal.getSchemaSnapshot();
+		for (const kind of Object.values(snapshot?.kinds ?? {})) tables.add(kind.table);
+		for (const definition of this.kinds.values()) tables.add(definition.table);
+		for (const table of tables) {
+			if (!this.hasTable(table)) continue;
+			const columns = new Set(this.database.query(`PRAGMA table_xinfo(${quoteString(table)})`).all().map((column) => column.name));
+			if (columns.has("created_at")) this.database.run(`ALTER TABLE ${quoteIdentifier(table)} DROP COLUMN "created_at"`);
+			if (columns.has("updated_at")) this.database.run(`ALTER TABLE ${quoteIdentifier(table)} DROP COLUMN "updated_at"`);
+		}
+	}
+	hasExistingStoreArtifacts() {
+		if (this.hasTable(LEGACY_KIND_VERSIONS_TABLE) || this.hasTable(LEGACY_APP_METADATA_TABLE)) return true;
+		for (const definition of this.kinds.values()) if (this.hasTable(definition.table)) return true;
+		return this.internal.keys().length > 0;
+	}
+	hasTable(name) {
+		return !!this.database.query(`SELECT 1 AS "exists" FROM "sqlite_master" WHERE "type" = 'table' AND "name" = ?`).get(name);
+	}
+	applySchemaMigrations(previousSnapshot) {
+		if (!previousSnapshot) return previousSnapshot;
+		const resolvedKinds = {};
+		const consumedPrevious = /* @__PURE__ */ new Set();
+		const usedRetags = /* @__PURE__ */ new Set();
+		for (const [key, previous] of Object.entries(previousSnapshot.kinds)) if (this.kinds.has(key)) {
+			resolvedKinds[key] = previous;
+			consumedPrevious.add(key);
+		}
+		for (const [previousKey, nextKey] of this.schemaPlan.renames) {
+			const previous = previousSnapshot.kinds[previousKey];
+			if (!previous) throw new Error(`Schema migration rename references unknown previous kind "${previousKey}".`);
+			const next = this.kinds.get(nextKey);
+			if (!next) throw new Error(`Schema migration rename target "${nextKey}" is not in the current registry.`);
+			if (resolvedKinds[nextKey]) throw new Error(`Schema migration rename target "${nextKey}" is already matched to a previous kind.`);
+			this.renameKind(previousKey, previous, nextKey, next);
+			resolvedKinds[nextKey] = {
+				...previous,
+				table: next.table
+			};
+			consumedPrevious.add(previousKey);
+		}
+		for (const [previousKey, previous] of Object.entries(previousSnapshot.kinds)) {
+			if (consumedPrevious.has(previousKey)) continue;
+			if (this.schemaPlan.drops.has(previousKey)) {
+				this.dropKind(previousKey, previous);
+				consumedPrevious.add(previousKey);
+				continue;
+			}
+			if (!this.kinds.has(previousKey)) throw new Error(`Previous kind "${previousKey}" is missing from the current registry and requires schema.migrate(...).`);
+		}
+		for (const [key, current] of this.kinds) {
+			const previous = resolvedKinds[key];
+			if (!previous) continue;
+			if (this.retagKindIfNeeded(key, previous, current)) usedRetags.add(key);
+		}
+		for (const key of this.schemaPlan.retags.keys()) if (!usedRetags.has(key)) throw new Error(`Schema migration retag for kind "${key}" did not match a changed current kind.`);
+		return {
+			kindstoreVersion: previousSnapshot.kindstoreVersion,
+			kinds: resolvedKinds
+		};
+	}
+	renameKind(previousKey, previous, nextKey, next) {
+		if (this.kinds.has(previousKey)) throw new Error(`Schema migration rename source "${previousKey}" still exists in the current registry.`);
+		if (!this.hasTable(previous.table)) throw new Error(`Schema migration rename source table "${previous.table}" does not exist.`);
+		if (previous.table !== next.table) {
+			if (this.hasTable(next.table)) throw new Error(`Schema migration rename target table "${next.table}" already exists.`);
+			this.database.run(`ALTER TABLE ${quoteIdentifier(previous.table)} RENAME TO ${quoteIdentifier(next.table)}`);
+		}
+		this.internal.moveKindVersion(previousKey, nextKey);
+	}
+	dropKind(previousKey, previous) {
+		if (this.kinds.has(previousKey)) throw new Error(`Schema migration drop source "${previousKey}" still exists in the current registry.`);
+		if (this.hasTable(previous.table)) this.database.run(`DROP TABLE IF EXISTS ${quoteIdentifier(previous.table)}`);
+		this.internal.deleteKindVersion(previousKey);
+	}
+	retagKindIfNeeded(key, previous, current) {
+		if (previous.tag === current.definition.tag) return false;
+		if (this.schemaPlan.retags.get(key) !== previous.tag) throw new Error(`Kind "${key}" changed tag from "${previous.tag}" to "${current.definition.tag}" and requires schema.migrate(...).`);
+		const updateIds = this.database.query(`UPDATE ${quoteIdentifier(current.table)} SET "id" = ? WHERE "id" = ?`);
+		for (const row of this.database.query(`SELECT "id" FROM ${quoteIdentifier(current.table)} ORDER BY "id" ASC`).iterate()) {
+			if (!row.id.startsWith(`${previous.tag}_`)) throw new Error(`Kind "${key}" cannot retag row "${row.id}" because it does not use the previous tag prefix "${previous.tag}_".`);
+			updateIds.run(`${current.definition.tag}_${row.id.slice(previous.tag.length + 1)}`, row.id);
+		}
+		return true;
+	}
+	ensureKindTable(definition) {
+		this.database.run(`CREATE TABLE IF NOT EXISTS ${quoteIdentifier(definition.table)} (
+        "id" TEXT PRIMARY KEY NOT NULL,
+        "payload" TEXT NOT NULL
+      ) STRICT`);
+	}
+	ensureGeneratedColumns(definition) {
+		const existing = new Set(this.database.query(`PRAGMA table_xinfo(${quoteString(definition.table)})`).all().map((column) => column.name));
+		for (const column of definition.columns.values()) {
+			if (existing.has(column.column)) continue;
+			this.database.run(`ALTER TABLE ${quoteIdentifier(definition.table)} ADD COLUMN ${quoteIdentifier(column.column)} ${column.type.toUpperCase()} GENERATED ALWAYS AS (${columnExpression(column.type, column.field)}) VIRTUAL`);
+		}
+	}
+	reconcileIndexes(definition, previous) {
+		const current = snapshotIndexes(definition);
+		if (previous) for (const index of Object.values(previous.indexes)) {
+			const next = current[index.sqliteName];
+			if (next && sameColumns(index.columns, next.columns)) continue;
+			this.database.run(`DROP INDEX IF EXISTS ${quoteIdentifier(index.sqliteName)}`);
+		}
+		for (const index of Object.values(current)) this.database.run(`CREATE INDEX IF NOT EXISTS ${quoteIdentifier(index.sqliteName)} ON ${quoteIdentifier(definition.table)} (${index.columns.join(", ")})`);
+	}
+	dropStaleGeneratedColumns(definition, previous) {
+		if (!previous) return;
+		const currentColumns = new Set(Array.from(definition.columns.values(), (column) => column.column));
+		const existingColumns = new Set(this.database.query(`PRAGMA table_xinfo(${quoteString(definition.table)})`).all().map((column) => column.name));
+		for (const column of Object.values(previous.columns)) {
+			if (currentColumns.has(column.column) || !existingColumns.has(column.column)) continue;
+			this.database.run(`ALTER TABLE ${quoteIdentifier(definition.table)} DROP COLUMN ${quoteIdentifier(column.column)}`);
+		}
+	}
+	createSchemaSnapshot() {
+		const kinds = {};
+		for (const [key, definition] of this.kinds) kinds[key] = snapshotKind(definition);
+		return {
+			kindstoreVersion: KINDSTORE_FORMAT_VERSION,
+			kinds
+		};
+	}
+	migrateKind(definition) {
+		const version = this.internal.getKindVersion(definition.key);
+		if (version == null) {
+			this.internal.setKindVersion(definition.key, definition.definition.version);
+			return;
+		}
+		if (version > definition.definition.version) throw new Error(`Kind "${definition.key}" is at version ${version}, but the registry declares version ${definition.definition.version}.`);
+		if (version === definition.definition.version) return;
+		const migrations = definition.definition.migrations;
+		if (!migrations) throw new Error(`Kind "${definition.key}" requires migrations from version ${version} to ${definition.definition.version}, but none were declared.`);
+		const updateRow = this.database.query(`UPDATE ${quoteIdentifier(definition.table)} SET "payload" = ? WHERE "id" = ?`);
+		this.database.transaction(() => {
+			const now = Date.now();
+			const context = { now };
+			for (const row of this.database.query(`SELECT "id", "payload" FROM ${quoteIdentifier(definition.table)} ORDER BY "id" ASC`).iterate()) {
+				let value = parsePayload(row.payload);
+				for (let currentVersion = version; currentVersion < definition.definition.version; currentVersion++) {
+					const step = migrations[currentVersion];
+					if (!step) throw new Error(`Kind "${definition.key}" is missing migration step ${currentVersion} -> ${currentVersion + 1}.`);
+					value = step(value, context);
+				}
+				updateRow.run(JSON.stringify(this.applyManagedTimestamps(definition, value, parsePayload(row.payload), now, false)), row.id);
+			}
+			this.internal.setKindVersion(definition.key, definition.definition.version);
+		})();
+	}
+	applyManagedTimestamps(definition, value, current, now, insert) {
+		const next = { ...value };
+		if (definition.createdAtField) if (current && Object.hasOwn(current, definition.createdAtField)) next[definition.createdAtField] = current[definition.createdAtField];
+		else if (insert) next[definition.createdAtField] = now;
+		else delete next[definition.createdAtField];
+		if (definition.updatedAtField) next[definition.updatedAtField] = now;
+		return definition.definition.schema.parse(next);
+	}
+};
+var KindCollectionRuntime = class {
+	database;
+	definition;
+	getStatement;
+	putStatement;
+	deleteStatement;
+	updateStatement;
+	constructor(database, definition) {
+		this.database = database;
+		this.definition = definition;
+		this.getStatement = database.query(`SELECT "id", "payload" FROM ${quoteIdentifier(definition.table)} WHERE "id" = ?`);
+		this.putStatement = database.query(`INSERT INTO ${quoteIdentifier(definition.table)} ("id", "payload") VALUES (?, ?)
+       ON CONFLICT("id") DO UPDATE SET "payload" = excluded."payload"`);
+		this.deleteStatement = database.query(`DELETE FROM ${quoteIdentifier(definition.table)} WHERE "id" = ?`);
+		this.updateStatement = database.query(`UPDATE ${quoteIdentifier(definition.table)} SET "payload" = ? WHERE "id" = ?`);
+	}
+	newId() {
+		return `${this.definition.definition.tag}_${nextUlid()}`;
+	}
+	get(id) {
+		assertTaggedId(this.definition.definition.tag, id);
+		const row = this.getStatement.get(id);
+		return row ? this.parseRow(row) : void 0;
+	}
+	put(id, value) {
+		assertTaggedId(this.definition.definition.tag, id);
+		return this.database.transaction(() => {
+			const row = this.getStatement.get(id);
+			const parsed = this.applyManagedTimestamps(value, row, Date.now(), !row);
+			this.putStatement.run(id, JSON.stringify(parsed));
+			return parsed;
+		})();
+	}
+	delete(id) {
+		assertTaggedId(this.definition.definition.tag, id);
+		return this.deleteStatement.run(id).changes > 0;
+	}
+	update(id, updater) {
+		assertTaggedId(this.definition.definition.tag, id);
+		return this.database.transaction(() => {
+			const row = this.getStatement.get(id);
+			if (!row) return;
+			const current = this.parseRow(row);
+			const parsed = this.applyManagedTimestamps(typeof updater === "function" ? updater(current) : {
+				...current,
+				...updater
+			}, row, Date.now(), false);
+			this.updateStatement.run(JSON.stringify(parsed), id);
+			return parsed;
+		})();
+	}
+	first(options = {}) {
+		const compiled = this.compileSelect({
+			where: options.where,
+			orderBy: options.orderBy,
+			limit: 1
+		});
+		const rows = this.database.query(compiled.sql).all(...compiled.values);
+		return rows[0] ? this.parseRow(rows[0]) : void 0;
+	}
+	findMany(options = {}) {
+		return Array.from(this.iterate(options));
+	}
+	findPage(options) {
+		if (!Number.isInteger(options.limit) || options.limit < 1) throw new Error(`Query limit for kind "${this.definition.key}" must be a positive integer when using findPage().`);
+		const orderEntries = resolveOrderBy(this.definition.columns, options.orderBy);
+		if (!orderEntries.length) throw new Error(`findPage() for kind "${this.definition.key}" requires an explicit orderBy.`);
+		const where = mergeWhereClauses(compileWhere(this.definition.columns, options.where), compilePageAfter(this.definition, orderEntries, options.after));
+		const sql = `SELECT "id", "payload" FROM ${quoteIdentifier(this.definition.table)}${where.sql}${compileOrderBy(orderEntries, true)} LIMIT ?`;
+		const rows = this.database.query(sql).all(...where.values, options.limit + 1);
+		const pageRows = rows.slice(0, options.limit);
+		const items = pageRows.map((row) => this.parseRow(row));
+		if (rows.length <= options.limit || !pageRows.length) return { items };
+		return {
+			items,
+			next: encodePageCursor(this.definition, orderEntries, pageRows[pageRows.length - 1], items.at(-1))
+		};
+	}
+	*iterate(options = {}) {
+		const compiled = this.compileSelect(options);
+		for (const row of this.database.query(compiled.sql).iterate(...compiled.values)) yield this.parseRow(row);
+	}
+	parseRow(row) {
+		return this.definition.definition.schema.parse(parsePayload(row.payload));
+	}
+	applyManagedTimestamps(value, row, now, insert) {
+		const current = row ? parsePayload(row.payload) : void 0;
+		const next = { ...value };
+		if (this.definition.createdAtField) if (current && Object.hasOwn(current, this.definition.createdAtField)) next[this.definition.createdAtField] = current[this.definition.createdAtField];
+		else if (insert) next[this.definition.createdAtField] = now;
+		else delete next[this.definition.createdAtField];
+		if (this.definition.updatedAtField) next[this.definition.updatedAtField] = now;
+		return this.definition.definition.schema.parse(next);
+	}
+	compileSelect(options) {
+		if (options.limit != null && (!Number.isInteger(options.limit) || options.limit < 0)) throw new Error(`Query limit for kind "${this.definition.key}" must be a non-negative integer.`);
+		const where = compileWhere(this.definition.columns, options.where);
+		const orderBy = compileOrderBy(resolveOrderBy(this.definition.columns, options.orderBy));
+		return {
+			sql: `SELECT "id", "payload" FROM ${quoteIdentifier(this.definition.table)}${where.sql}${orderBy}${options.limit == null ? "" : " LIMIT ?"}`,
+			values: options.limit == null ? where.values : [...where.values, options.limit]
+		};
+	}
+};
+var MetadataRuntime = class {
+	database;
+	definitions;
+	getStatement;
+	setStatement;
+	deleteStatement;
+	constructor(database, definitions) {
+		this.database = database;
+		this.definitions = definitions;
+		this.getStatement = database.query(`SELECT "payload" FROM ${quoteIdentifier(APP_METADATA_TABLE)} WHERE "key" = ?`);
+		this.setStatement = database.query(`INSERT INTO ${quoteIdentifier(APP_METADATA_TABLE)} ("key", "payload", "created_at", "updated_at") VALUES (?, ?, ?, ?)
+       ON CONFLICT("key") DO UPDATE SET "payload" = excluded."payload", "updated_at" = excluded."updated_at"`);
+		this.deleteStatement = database.query(`DELETE FROM ${quoteIdentifier(APP_METADATA_TABLE)} WHERE "key" = ?`);
+	}
+	get(key) {
+		const schema = this.definitions[key];
+		if (!schema) throw new Error(`Metadata key "${key}" is not declared.`);
+		const row = this.getStatement.get(key);
+		return row ? schema.parse(parsePayload(row.payload)) : void 0;
+	}
+	set(key, value) {
+		const schema = this.definitions[key];
+		if (!schema) throw new Error(`Metadata key "${key}" is not declared.`);
+		const parsed = schema.parse(value);
+		const now = Date.now();
+		this.setStatement.run(key, JSON.stringify(parsed), now, now);
+		return parsed;
+	}
+	delete(key) {
+		if (!this.definitions[key]) throw new Error(`Metadata key "${key}" is not declared.`);
+		return this.deleteStatement.run(key).changes > 0;
+	}
+	update(key, updater) {
+		return this.database.transaction(() => this.set(key, updater(this.get(key))))();
+	}
+};
+var InternalMetadataRuntime = class {
+	database;
+	getStatement;
+	deleteStatement;
+	setStatement;
+	constructor(database) {
+		this.database = database;
+		this.getStatement = database.query(`SELECT "payload" FROM ${quoteIdentifier(INTERNAL_TABLE)} WHERE "key" = ?`);
+		this.deleteStatement = database.query(`DELETE FROM ${quoteIdentifier(INTERNAL_TABLE)} WHERE "key" = ?`);
+		this.setStatement = database.query(`INSERT INTO ${quoteIdentifier(INTERNAL_TABLE)} ("key", "payload", "updated_at") VALUES (?, ?, ?)
+       ON CONFLICT("key") DO UPDATE SET "payload" = excluded."payload", "updated_at" = excluded."updated_at"`);
+	}
+	get(key) {
+		const row = this.getStatement.get(key);
+		return row ? parsePayload(row.payload) : void 0;
+	}
+	getNumber(key) {
+		const value = this.get(key);
+		if (value == null) return;
+		if (typeof value !== "number") throw new Error(`Internal metadata key "${key}" must be a number.`);
+		return value;
+	}
+	set(key, value) {
+		this.setStatement.run(key, JSON.stringify(value), Date.now());
+	}
+	delete(key) {
+		this.deleteStatement.run(key);
+	}
+	keys() {
+		return this.database.query(`SELECT "key" FROM ${quoteIdentifier(INTERNAL_TABLE)} ORDER BY "key" ASC`).all().map((row) => row.key);
+	}
+	getKindVersion(kind) {
+		const version = this.getKindVersions()?.[kind];
+		return typeof version === "number" ? version : void 0;
+	}
+	setKindVersion(kind, version) {
+		const current = this.getKindVersions();
+		const next = current ? {
+			...current,
+			[kind]: version
+		} : { [kind]: version };
+		this.set(KIND_VERSIONS_KEY, next);
+	}
+	deleteKindVersion(kind) {
+		const current = this.getKindVersions();
+		if (!current) return;
+		const next = { ...current };
+		delete next[kind];
+		if (Object.keys(next).length) {
+			this.set(KIND_VERSIONS_KEY, next);
+			return;
+		}
+		this.delete(KIND_VERSIONS_KEY);
+	}
+	moveKindVersion(previousKind, nextKind) {
+		const version = this.getKindVersion(previousKind);
+		if (version == null) return;
+		if (this.getKindVersion(nextKind) != null) throw new Error(`Schema migration cannot move kind version from "${previousKind}" to "${nextKind}" because the target already has a version entry.`);
+		this.setKindVersion(nextKind, version);
+		this.deleteKindVersion(previousKind);
+	}
+	getSchemaSnapshot() {
+		const snapshot = this.get(SCHEMA_SNAPSHOT_KEY);
+		if (snapshot == null) return;
+		if (!isRecord(snapshot) || !Number.isInteger(snapshot.kindstoreVersion) || !isRecord(snapshot.kinds)) throw new Error(`Internal metadata key "${SCHEMA_SNAPSHOT_KEY}" is malformed.`);
+		for (const [kindKey, kind] of Object.entries(snapshot.kinds)) {
+			if (!isRecord(kind) || typeof kind.tag !== "string" || typeof kind.table !== "string" || !Number.isInteger(kind.version) || !isRecord(kind.columns) || !isRecord(kind.indexes)) throw new Error(`Internal metadata key "${SCHEMA_SNAPSHOT_KEY}" has an invalid kind entry for "${kindKey}".`);
+			for (const [field, column] of Object.entries(kind.columns)) if (!isRecord(column) || column.field !== field || typeof column.column !== "string" || typeof column.type !== "string" || !isSqliteTypeHint(column.type) || typeof column.single !== "boolean") throw new Error(`Internal metadata key "${SCHEMA_SNAPSHOT_KEY}" has an invalid column entry for "${kindKey}.${field}".`);
+			for (const [indexName, index] of Object.entries(kind.indexes)) if (!isRecord(index) || index.sqliteName !== indexName || !Array.isArray(index.columns) || index.columns.some((column) => typeof column !== "string")) throw new Error(`Internal metadata key "${SCHEMA_SNAPSHOT_KEY}" has an invalid index entry for "${kindKey}.${indexName}".`);
+		}
+		return snapshot;
+	}
+	setSchemaSnapshot(snapshot) {
+		this.set(SCHEMA_SNAPSHOT_KEY, snapshot);
+	}
+	getKindVersions() {
+		const versions = this.get(KIND_VERSIONS_KEY);
+		if (versions == null) return;
+		if (!isRecord(versions)) throw new Error(`Internal metadata key "${KIND_VERSIONS_KEY}" is malformed.`);
+		for (const [kind, version] of Object.entries(versions)) if (typeof version !== "number" || !Number.isInteger(version) || version < 1) throw new Error(`Internal metadata key "${KIND_VERSIONS_KEY}" has an invalid version for "${kind}".`);
+		return versions;
+	}
+};
+function normalizeSchemaPlan(schemaDefinition) {
+	const plan = {
+		drops: /* @__PURE__ */ new Set(),
+		renames: /* @__PURE__ */ new Map(),
+		retags: /* @__PURE__ */ new Map()
+	};
+	if (!schemaDefinition) return plan;
+	schemaDefinition.migrate(new SchemaMigrationPlannerRuntime(plan));
+	return plan;
+}
+var SchemaMigrationPlannerRuntime = class {
+	plan;
+	constructor(plan) {
+		this.plan = plan;
+	}
+	rename(previousKindKey, nextKindKey) {
+		if (!previousKindKey || !nextKindKey) throw new Error("Schema migration rename keys must be non-empty.");
+		if (previousKindKey === nextKindKey) throw new Error(`Schema migration rename from "${previousKindKey}" to itself is not allowed.`);
+		if (this.plan.drops.has(previousKindKey) || this.plan.renames.has(previousKindKey)) throw new Error(`Schema migration already defines an operation for previous kind "${previousKindKey}".`);
+		for (const existingNextKey of this.plan.renames.values()) if (existingNextKey === nextKindKey) throw new Error(`Schema migration already maps a previous kind to "${nextKindKey}".`);
+		this.plan.renames.set(previousKindKey, nextKindKey);
+		return this;
+	}
+	drop(previousKindKey) {
+		if (!previousKindKey) throw new Error("Schema migration drop key must be non-empty.");
+		if (this.plan.renames.has(previousKindKey) || this.plan.drops.has(previousKindKey)) throw new Error(`Schema migration already defines an operation for previous kind "${previousKindKey}".`);
+		this.plan.drops.add(previousKindKey);
+		return this;
+	}
+	retag(kindKey, previousTag) {
+		if (!kindKey || !previousTag) throw new Error("Schema migration retag arguments must be non-empty.");
+		if (this.plan.retags.has(kindKey)) throw new Error(`Schema migration already defines a retag for kind "${kindKey}".`);
+		this.plan.retags.set(kindKey, previousTag);
+		return this;
+	}
+};
+function normalizeKinds(kinds) {
+	const definitions = /* @__PURE__ */ new Map();
+	const seenTags = /* @__PURE__ */ new Set();
+	const seenTables = /* @__PURE__ */ new Set();
+	for (const [key, value] of Object.entries(kinds)) {
+		if (!(value instanceof KindDefinition)) throw new Error(`Property "${key}" is not a kind definition.`);
+		if (RESERVED_STORE_KEYS.has(key)) throw new Error(`Kind key "${key}" is reserved.`);
+		if (seenTags.has(value.tag)) throw new Error(`Kind tag "${value.tag}" is declared more than once.`);
+		const table = snakeCase(key);
+		if (seenTables.has(table)) throw new Error(`Kind key "${key}" collides with an existing table name.`);
+		const shape = value.schema.shape;
+		if (value.createdAtField && value.createdAtField === value.updatedAtField) throw new Error(`Kind "${value.tag}" cannot use "${value.createdAtField}" for both createdAt and updatedAt.`);
+		validateManagedTimestampField(value, shape, value.createdAtField, "createdAt");
+		validateManagedTimestampField(value, shape, value.updatedAtField, "updatedAt");
+		seenTags.add(value.tag);
+		seenTables.add(table);
+		definitions.set(key, {
+			key,
+			table,
+			columns: normalizeColumns(value),
+			createdAtField: value.createdAtField,
+			updatedAtField: value.updatedAtField,
+			definition: value
+		});
+	}
+	return definitions;
+}
+function normalizeColumns(definition) {
+	const shape = definition.schema.shape;
+	const columns = /* @__PURE__ */ new Map();
+	const seenColumns = /* @__PURE__ */ new Set();
+	for (const index of definition.indexes.values()) {
+		assertTopLevelField(definition.tag, shape, index.field);
+		const column = columnName(index.field);
+		if (seenColumns.has(column)) throw new Error(`Kind "${definition.tag}" has multiple indexed fields that map to column "${column}".`);
+		seenColumns.add(column);
+		columns.set(index.field, {
+			field: index.field,
+			column,
+			single: index.single,
+			type: index.type ?? inferSqliteType(shape[index.field], definition.tag, index.field)
+		});
+	}
+	for (const multiIndex of definition.multiIndexes) for (const [field] of multiIndex.fields) {
+		if (columns.has(field)) continue;
+		assertTopLevelField(definition.tag, shape, field);
+		const column = columnName(field);
+		if (seenColumns.has(column)) throw new Error(`Kind "${definition.tag}" has multiple indexed fields that map to column "${column}".`);
+		seenColumns.add(column);
+		columns.set(field, {
+			field,
+			column,
+			single: false,
+			type: inferSqliteType(shape[field], definition.tag, field)
+		});
+	}
+	return columns;
+}
+function assertTopLevelField(tag, shape, field) {
+	if (!(field in shape)) throw new Error(`Kind "${tag}" references unknown field "${field}".`);
+}
+function validateManagedTimestampField(definition, shape, field, name) {
+	if (!field) return;
+	assertTopLevelField(definition.tag, shape, field);
+	if (inferSqliteType(shape[field], definition.tag, field) !== "integer") throw new Error(`Kind "${definition.tag}" ${name} field "${field}" must be an integer.`);
+}
+function inferSqliteType(schema, tag, field) {
+	while (schema?._def?.type === "optional" || schema?._def?.type === "nullable" || schema?._def?.type === "default" || schema?._def?.type === "readonly" || schema?._def?.type === "catch") schema = schema._def.innerType;
+	switch (schema?._def?.type) {
+		case "string":
+		case "enum": return "text";
+		case "boolean": return "integer";
+		case "literal": {
+			const values = schema._def.values;
+			const value = values instanceof Set ? values.values().next().value : values?.[0];
+			return typeof value === "number" || typeof value === "boolean" ? "integer" : "text";
+		}
+		case "number": return schema._def.checks?.some((check) => check.isInt) ? "integer" : "real";
+		default: throw new Error(`Kind "${tag}" field "${field}" needs an explicit SQLite type hint.`);
+	}
+}
+function compileWhere(columns, where) {
+	if (!where || !Object.keys(where).length) return {
+		sql: "",
+		values: []
+	};
+	const parts = [];
+	const values = [];
+	for (const [field, operand] of Object.entries(where)) {
+		const column = columns.get(field);
+		if (!column) throw new Error(`Field "${field}" is not indexed and cannot be queried.`);
+		if (isFilterOperators(operand)) {
+			if (operand.in) {
+				if (!operand.in.length) {
+					parts.push("0 = 1");
+					continue;
+				}
+				parts.push(`${quoteIdentifier(column.column)} IN (${operand.in.map(() => "?").join(", ")})`);
+				values.push(...operand.in);
+			}
+			if (operand.gt != null) {
+				parts.push(`${quoteIdentifier(column.column)} > ?`);
+				values.push(operand.gt);
+			}
+			if (operand.gte != null) {
+				parts.push(`${quoteIdentifier(column.column)} >= ?`);
+				values.push(operand.gte);
+			}
+			if (operand.lt != null) {
+				parts.push(`${quoteIdentifier(column.column)} < ?`);
+				values.push(operand.lt);
+			}
+			if (operand.lte != null) {
+				parts.push(`${quoteIdentifier(column.column)} <= ?`);
+				values.push(operand.lte);
+			}
+			continue;
+		}
+		if (operand == null) {
+			parts.push(`${quoteIdentifier(column.column)} IS NULL`);
+			continue;
+		}
+		parts.push(`${quoteIdentifier(column.column)} = ?`);
+		values.push(operand);
+	}
+	return {
+		sql: parts.length ? ` WHERE ${parts.join(" AND ")}` : "",
+		values
+	};
+}
+function mergeWhereClauses(...clauses) {
+	const parts = [];
+	const values = [];
+	for (const clause of clauses) {
+		if (!clause.sql) continue;
+		parts.push(clause.sql.replace(/^ WHERE /, ""));
+		values.push(...clause.values);
+	}
+	return {
+		sql: parts.length ? ` WHERE ${parts.join(" AND ")}` : "",
+		values
+	};
+}
+function resolveOrderBy(columns, orderBy) {
+	if (!orderBy || !Object.keys(orderBy).length) return [];
+	return Object.entries(orderBy).map(([field, direction]) => {
+		if (!direction) throw new Error(`Order direction for "${field}" is required.`);
+		const column = columns.get(field);
+		if (!column) throw new Error(`Field "${field}" is not indexed and cannot be ordered.`);
+		return {
+			field,
+			direction,
+			column
+		};
+	});
+}
+function tieBreakerDirection(orderBy) {
+	return orderBy[orderBy.length - 1].direction;
+}
+function compileOrderBy(orderBy, includeIdTieBreaker = false) {
+	if (!orderBy.length) return "";
+	const parts = orderBy.map(({ column, direction }) => `${quoteIdentifier(column.column)} ${direction.toUpperCase()}`);
+	if (includeIdTieBreaker) parts.push(`"id" ${tieBreakerDirection(orderBy).toUpperCase()}`);
+	return ` ORDER BY ${parts.join(", ")}`;
+}
+function compilePageAfter(definition, orderBy, after) {
+	if (!after) return {
+		sql: "",
+		values: []
+	};
+	const cursor = decodePageCursor(after);
+	if (cursor.version !== PAGE_CURSOR_VERSION) throw new Error(`Unsupported findPage() cursor version "${cursor.version}".`);
+	if (cursor.tag !== definition.definition.tag) throw new Error(`findPage() cursor does not belong to kind "${definition.key}".`);
+	if (cursor.order.length !== orderBy.length) throw new Error(`findPage() cursor does not match the requested orderBy for kind "${definition.key}".`);
+	for (const [index, [field, direction]] of cursor.order.entries()) {
+		const expected = orderBy[index];
+		if (field !== expected.field || direction !== expected.direction) throw new Error(`findPage() cursor does not match the requested orderBy for kind "${definition.key}".`);
+	}
+	if (cursor.values.length !== orderBy.length) throw new Error(`findPage() cursor is malformed for kind "${definition.key}".`);
+	const disjuncts = [];
+	const values = [];
+	for (let pivot = 0; pivot < orderBy.length; pivot += 1) {
+		const parts = [];
+		for (let index = 0; index < pivot; index += 1) {
+			const value = cursor.values[index];
+			if (value == null) throw new Error(`findPage() cursor cannot continue on nullish ordered field "${orderBy[index].field}".`);
+			parts.push(`${quoteIdentifier(orderBy[index].column.column)} = ?`);
+			values.push(value);
+		}
+		const pivotValue = cursor.values[pivot];
+		if (pivotValue == null) throw new Error(`findPage() cursor cannot continue on nullish ordered field "${orderBy[pivot].field}".`);
+		parts.push(`${quoteIdentifier(orderBy[pivot].column.column)} ${orderBy[pivot].direction === "asc" ? ">" : "<"} ?`);
+		values.push(pivotValue);
+		disjuncts.push(`(${parts.join(" AND ")})`);
+	}
+	const tieBreakerParts = orderBy.map(({ column }, index) => {
+		const value = cursor.values[index];
+		if (value == null) throw new Error(`findPage() cursor cannot continue on nullish ordered field "${orderBy[index].field}".`);
+		values.push(value);
+		return `${quoteIdentifier(column.column)} = ?`;
+	});
+	values.push(cursor.id);
+	tieBreakerParts.push(`"id" ${tieBreakerDirection(orderBy) === "asc" ? ">" : "<"} ?`);
+	disjuncts.push(`(${tieBreakerParts.join(" AND ")})`);
+	return {
+		sql: ` WHERE (${disjuncts.join(" OR ")})`,
+		values
+	};
+}
+function encodePageCursor(definition, orderBy, row, value) {
+	const values = orderBy.map(({ field }) => {
+		const fieldValue = value[field];
+		if (fieldValue == null) throw new Error(`findPage() cannot paginate on nullish ordered field "${field}".`);
+		return fieldValue;
+	});
+	return Buffer.from(JSON.stringify({
+		version: PAGE_CURSOR_VERSION,
+		tag: definition.definition.tag,
+		order: orderBy.map(({ field, direction }) => [field, direction]),
+		values,
+		id: row.id
+	})).toString("base64url");
+}
+function decodePageCursor(cursor) {
+	let parsed;
+	try {
+		parsed = JSON.parse(Buffer.from(cursor, "base64url").toString("utf8"));
+	} catch {
+		throw new Error("findPage() cursor is malformed.");
+	}
+	if (!isRecord(parsed)) throw new Error("findPage() cursor is malformed.");
+	const { version, tag, order, values, id } = parsed;
+	if (version !== PAGE_CURSOR_VERSION || typeof tag !== "string" || !Array.isArray(order) || !Array.isArray(values) || typeof id !== "string") throw new Error("findPage() cursor is malformed.");
+	for (const entry of order) if (!Array.isArray(entry) || entry.length !== 2 || typeof entry[0] !== "string" || entry[1] !== "asc" && entry[1] !== "desc") throw new Error("findPage() cursor is malformed.");
+	return {
+		version,
+		tag,
+		order,
+		values,
+		id
+	};
+}
+function columnName(field) {
+	const column = snakeCase(field);
+	return RESERVED_COLUMN_NAMES.has(column) ? `doc_${column}` : column;
+}
+function snapshotKind(definition) {
+	const columns = {};
+	for (const column of definition.columns.values()) columns[column.field] = {
+		field: column.field,
+		column: column.column,
+		type: column.type,
+		single: column.single
+	};
+	return {
+		tag: definition.definition.tag,
+		table: definition.table,
+		version: definition.definition.version,
+		columns,
+		indexes: snapshotIndexes(definition)
+	};
+}
+function snapshotIndexes(definition) {
+	const indexes = {};
+	for (const column of definition.columns.values()) {
+		if (!column.single) continue;
+		const sqliteName = indexName(definition.table, column.column);
+		indexes[sqliteName] = {
+			sqliteName,
+			columns: [quoteIdentifier(column.column)]
+		};
+	}
+	for (const multiIndex of definition.definition.multiIndexes) {
+		const sqliteName = indexName(definition.table, snakeCase(multiIndex.name));
+		indexes[sqliteName] = {
+			sqliteName,
+			columns: multiIndex.fields.map(([field, direction]) => `${quoteIdentifier(definition.columns.get(field).column)} ${direction.toUpperCase()}`)
+		};
+	}
+	return indexes;
+}
+//#endregion
+//#region src/store.ts
+function kindstore(input) {
+	const { connection, metadata, schema, ...rest } = input;
+	return createStore(connection, rest, metadata ?? {}, schema);
+}
+//#endregion
+export { KindDefinition, kind, kindstore };

package/package.json

@@ -1,13 +1,53 @@
 {
   "name": "kindstore",
-  "version": "0.0.0",
-  "description": "",
-  "main": "index.js",
-  "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
-  },
-  "keywords": [],
-  "author": "",
+  "version": "0.1.1",
+  "description": "A lightweight, typed document store on SQLite with Zod schemas, indexed queries, and explicit migrations.",
   "license": "MIT",
-  "type": "commonjs"
-}
+  "author": "Alec Larson",
+  "homepage": "https://github.com/alloc/kindstore#readme",
+  "bugs": {
+    "url": "https://github.com/alloc/kindstore/issues"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/alloc/kindstore.git"
+  },
+  "keywords": [
+    "bun",
+    "sqlite",
+    "document-store",
+    "zod",
+    "migrations",
+    "typesafe"
+  ],
+  "files": [
+    "dist"
+  ],
+  "type": "module",
+  "exports": {
+    "types": "./dist/index.d.mts",
+    "import": "./dist/index.mjs"
+  },
+  "sideEffects": false,
+  "engines": {
+    "bun": ">=1.3.11"
+  },
+  "dependencies": {
+    "ulid": "^3.0.2",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/bun": "^1.3.11",
+    "oxfmt": "^0.43.0",
+    "oxlint": "^1.58.0",
+    "tsdown": "^0.21.7",
+    "typescript": "^6.0.2"
+  },
+  "scripts": {
+    "dev": "tsdown --sourcemap --watch",
+    "build": "tsdown",
+    "format": "oxfmt .",
+    "lint": "oxlint src",
+    "test": "bun test"
+  }
+}

package/readme.md

@@ -1 +0,0 @@
-Coming soon...