@prisma-idb/family-idb 0.0.0

package/dist/exports/control.mjs

@@ -0,0 +1,573 @@
+import { t as validateContract } from "../validate-BLnItEKs.mjs";
+import { VERIFY_CODE_SCHEMA_FAILURE, VERIFY_CODE_TARGET_MISMATCH } from "@prisma/orm-framework/components/control";
+//#region src/core/emission.ts
+/**
+* Converts a JavaScript primitive or plain object into a TypeScript type-literal
+* string. Arrays become `readonly [...]` tuples; objects become `{ readonly k: v }`
+* type literals; strings are single-quoted with escaping.
+*/
+function serializeValue(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	if (typeof value === "string") return `'${value.replace(/\\/g, "\\\\").replace(/'/g, "\\'")}'`;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	if (typeof value === "bigint") return `${value}n`;
+	if (Array.isArray(value)) return `readonly [${value.map((v) => serializeValue(v)).join(", ")}]`;
+	if (typeof value === "object") {
+		const entries = [];
+		for (const [k, v] of Object.entries(value)) entries.push(`readonly ${serializeObjectKey(k)}: ${serializeValue(v)}`);
+		return `{ ${entries.join("; ")} }`;
+	}
+	return "unknown";
+}
+/**
+* Converts an object key to a safe TypeScript identifier. If the key is already a
+* valid identifier it is returned as-is; otherwise it is wrapped in single-quoted
+* string literal form.
+*/
+function serializeObjectKey(key) {
+	if (/^[$A-Z_a-z][$\w]*$/.test(key)) return key;
+	return serializeValue(key);
+}
+/**
+* IDB family emission plugin.
+*
+* Registered as `emission` on {@link IdbFamilyDescriptor}. The Prisma 8 emitter
+* calls these methods when generating `contract.d.ts` for any schema that targets the
+* IDB family. Each method returns a raw TypeScript source string that the emitter
+* splices into the generated file at the appropriate location.
+*
+* @see `generateContractDts` in `@prisma/orm-toolchain`.
+*/
+const idbEmission = {
+	id: "idb",
+	/**
+	* Serializes the full `storage` section of the contract into a TypeScript type
+	* literal. The result is used as the first generic argument of `ContractType<...>`
+	* in the generated `contract.d.ts`.
+	*
+	* For IDB the storage shape is:
+	* ```ts
+	* { readonly stores: { readonly <storeName>: { readonly keyPath: '...'; ... }; ... };
+	*   readonly storageHash: <storageHashTypeName> }
+	* ```
+	*
+	* @param contract            - The resolved Prisma contract.
+	* @param storageHashTypeName - Emitter-provided name of the `StorageHash` type alias
+	*                              to embed (e.g. `'StorageHash'`).
+	*/
+	generateStorageType(contract, storageHashTypeName) {
+		const storage = contract.storage;
+		const stores = [];
+		for (const [storeName, store] of Object.entries(storage.stores).sort(([a], [b]) => a.localeCompare(b))) {
+			const storeParts = [`readonly keyPath: ${serializeValue(store.keyPath)}`];
+			if (store.autoIncrement !== void 0) storeParts.push(`readonly autoIncrement: ${store.autoIncrement}`);
+			const indexes = store.indexes ?? {};
+			if (Object.keys(indexes).length > 0) {
+				const indexEntries = [];
+				for (const [indexName, index] of Object.entries(indexes).sort(([a], [b]) => a.localeCompare(b))) {
+					const indexParts = [`readonly keyPath: ${serializeValue(index.keyPath)}`, `readonly unique: ${index.unique}`];
+					if (index.multiEntry !== void 0) indexParts.push(`readonly multiEntry: ${index.multiEntry}`);
+					indexEntries.push(`readonly ${serializeObjectKey(indexName)}: { ${indexParts.join("; ")} }`);
+				}
+				storeParts.push(`readonly indexes: { ${indexEntries.join("; ")} }`);
+			} else storeParts.push(`readonly indexes: Record<string, never>`);
+			stores.push(`readonly ${serializeObjectKey(storeName)}: { ${storeParts.join("; ")} }`);
+		}
+		const storesType = stores.length > 0 ? `{ ${stores.join("; ")} }` : "Record<string, never>";
+		const nsEntries = [];
+		for (const [nsId, ns] of Object.entries(storage.namespaces ?? {}).sort(([a], [b]) => a.localeCompare(b))) {
+			const entriesObj = ns.entries ?? {};
+			const entriesType = Object.keys(entriesObj).length === 0 ? "Record<string, never>" : serializeValue(entriesObj);
+			nsEntries.push(`readonly ${serializeObjectKey(nsId)}: { readonly id: ${serializeValue(ns.id)}; readonly entries: ${entriesType} }`);
+		}
+		return `{ readonly stores: ${storesType}; readonly namespaces: ${nsEntries.length > 0 ? `{ ${nsEntries.join("; ")} }` : "Record<string, never>"}; readonly storageHash: ${storageHashTypeName} }`;
+	},
+	/**
+	* Serializes the per-model storage metadata into a TypeScript type literal.
+	* The result is used as the `storage` field of the model's entry in the
+	* generated `models` type.
+	*
+	* For IDB, each model maps to exactly one object store:
+	* ```ts
+	* { readonly storeName: '<name>'; readonly keyPath: '<field>' }
+	* ```
+	*
+	* @param _modelName - The Prisma model name (unused; provided for API symmetry).
+	* @param model      - The resolved `ContractModel` whose `storage` is cast to
+	*                     {@link IdbModelStorage}.
+	*/
+	generateModelStorageType(_modelName, model) {
+		const idbModel = model;
+		return [`{ readonly storeName: ${serializeValue(idbModel.storage.storeName)}`, `readonly keyPath: ${serializeValue(idbModel.storage.keyPath)} }`].join("; ");
+	},
+	/**
+	* Returns the `import type` lines prepended to `contract.d.ts` that bring
+	* IDB-family types into scope.
+	*
+	* Imports {@link IdbContractWithTypeMaps} (the phantom wrapper used by
+	* {@link getContractWrapper}) and {@link IdbTypeMaps} (used by
+	* {@link getTypeMapsExpression}).
+	*/
+	getFamilyImports() {
+		return ["import type { IdbContractWithTypeMaps, IdbTypeMaps } from '@prisma-idb/target-idb/pack';"];
+	},
+	/**
+	* Returns additional type alias declarations appended to `contract.d.ts`
+	* after the codec and operation type aliases.
+	*
+	* For IDB this exports `LaneCodecTypes` (used by the generated client to
+	* look up codec input/output pairs) as a simple alias of the assembled
+	* `CodecTypes`. IDB has no query-operation types, so no further aliases
+	* are needed.
+	*/
+	getFamilyTypeAliases() {
+		return "export type LaneCodecTypes = CodecTypes;";
+	},
+	/**
+	* Returns the TypeScript expression for the `TypeMaps<...>` generic
+	* instantiation written into `contract.d.ts`.
+	*
+	* IDB has no operation types or query-operation types, so the expression
+	* uses the three-argument form of {@link IdbTypeMaps}.
+	*/
+	getTypeMapsExpression() {
+		return "IdbTypeMaps<CodecTypes, FieldOutputTypes, FieldInputTypes>";
+	},
+	/**
+	* Returns the final `export type Contract = ...` declaration and convenience
+	* re-exports derived from it.
+	*
+	* @param contractBaseName - Emitter-provided name of the base contract type
+	*                           (always `'ContractBase'`).
+	* @param typeMapsName     - Emitter-provided name of the assembled TypeMaps type
+	*                           (always `'TypeMaps'`).
+	*/
+	getContractWrapper(contractBaseName, typeMapsName) {
+		return [
+			`export type Contract = IdbContractWithTypeMaps<${contractBaseName}, ${typeMapsName}>;`,
+			"",
+			"export type Stores = Contract['storage']['stores'];"
+		].join("\n");
+	}
+};
+//#endregion
+//#region src/core/schema-verify.ts
+function passNode(kind, name, contractPath, children = []) {
+	return {
+		status: "pass",
+		kind,
+		name,
+		contractPath,
+		code: "ok",
+		message: `${name} matches`,
+		expected: null,
+		actual: null,
+		children
+	};
+}
+function failNode(kind, name, contractPath, code, message, expected, actual, children = []) {
+	return {
+		status: "fail",
+		kind,
+		name,
+		contractPath,
+		code,
+		message,
+		expected,
+		actual,
+		children
+	};
+}
+function warnNode(kind, name, contractPath, code, message, expected, actual, children = []) {
+	return {
+		status: "warn",
+		kind,
+		name,
+		contractPath,
+		code,
+		message,
+		expected,
+		actual,
+		children
+	};
+}
+function countStatuses(nodes) {
+	let pass = 0, warn = 0, fail = 0, totalNodes = 0;
+	const stack = [...nodes];
+	while (stack.length > 0) {
+		const node = stack.pop();
+		totalNodes++;
+		if (node.status === "pass") pass++;
+		else if (node.status === "warn") warn++;
+		else fail++;
+		stack.push(...node.children);
+	}
+	return {
+		pass,
+		warn,
+		fail,
+		totalNodes
+	};
+}
+function verifyIndex(indexName, contractIndex, actualIndex, storeName, storePath, issues) {
+	const indexPath = `${storePath}.indexes.${indexName}`;
+	if (actualIndex === void 0) {
+		const msg = `Index "${indexName}" defined in contract is missing from manifest schema`;
+		issues.push({
+			kind: "missing_column",
+			table: storeName,
+			column: indexName,
+			message: msg,
+			path: [storeName, indexName]
+		});
+		return failNode("index", indexName, indexPath, "missing_column", msg, contractIndex, void 0);
+	}
+	const children = [];
+	if (contractIndex.keyPath !== actualIndex.keyPath) {
+		const msg = `Index "${indexName}" keyPath mismatch: expected "${contractIndex.keyPath}", got "${actualIndex.keyPath}"`;
+		issues.push({
+			kind: "index_mismatch",
+			table: storeName,
+			indexOrConstraint: indexName,
+			message: msg,
+			path: [storeName, indexName]
+		});
+		children.push(failNode("field", "keyPath", `${indexPath}.keyPath`, "index_mismatch", msg, contractIndex.keyPath, actualIndex.keyPath));
+	} else children.push(passNode("field", "keyPath", `${indexPath}.keyPath`));
+	if ((contractIndex.unique ?? false) !== (actualIndex.unique ?? false)) {
+		const msg = `Index "${indexName}" unique mismatch: expected ${contractIndex.unique}, got ${actualIndex.unique}`;
+		issues.push({
+			kind: "index_mismatch",
+			table: storeName,
+			indexOrConstraint: indexName,
+			message: msg,
+			path: [storeName, indexName]
+		});
+		children.push(failNode("field", "unique", `${indexPath}.unique`, "index_mismatch", msg, contractIndex.unique, actualIndex.unique));
+	} else children.push(passNode("field", "unique", `${indexPath}.unique`));
+	const contractME = contractIndex.multiEntry ?? false;
+	const actualME = actualIndex.multiEntry ?? false;
+	if (contractME !== actualME) {
+		const msg = `Index "${indexName}" multiEntry mismatch: expected ${contractME}, got ${actualME}`;
+		issues.push({
+			kind: "index_mismatch",
+			table: storeName,
+			indexOrConstraint: indexName,
+			message: msg,
+			path: [storeName, indexName]
+		});
+		children.push(failNode("field", "multiEntry", `${indexPath}.multiEntry`, "index_mismatch", msg, contractME, actualME));
+	} else if (contractME) children.push(passNode("field", "multiEntry", `${indexPath}.multiEntry`));
+	if (children.some((c) => c.status === "fail")) return failNode("index", indexName, indexPath, "index_mismatch", `Index "${indexName}" has mismatches`, null, null, children);
+	return passNode("index", indexName, indexPath, children);
+}
+function verifyStore(storeName, contractStore, actualStore, strict, issues) {
+	const storePath = `storage.stores.${storeName}`;
+	if (actualStore === void 0) {
+		const msg = `Object store "${storeName}" defined in contract is missing from manifest schema`;
+		issues.push({
+			kind: "missing_table",
+			table: storeName,
+			message: msg,
+			path: [storeName]
+		});
+		return failNode("collection", storeName, storePath, "missing_table", msg, contractStore, void 0);
+	}
+	const children = [];
+	if (contractStore.keyPath !== actualStore.keyPath) {
+		const msg = `Store "${storeName}" keyPath mismatch: expected "${contractStore.keyPath}", got "${actualStore.keyPath}"`;
+		issues.push({
+			kind: "primary_key_mismatch",
+			table: storeName,
+			message: msg,
+			path: [storeName]
+		});
+		children.push(failNode("field", "keyPath", `${storePath}.keyPath`, "primary_key_mismatch", msg, contractStore.keyPath, actualStore.keyPath));
+	} else children.push(passNode("field", "keyPath", `${storePath}.keyPath`));
+	const contractAI = contractStore.autoIncrement ?? false;
+	const actualAI = actualStore.autoIncrement ?? false;
+	if (contractAI !== actualAI) {
+		const msg = `Store "${storeName}" autoIncrement mismatch: expected ${contractAI}, got ${actualAI}`;
+		issues.push({
+			kind: "type_mismatch",
+			table: storeName,
+			message: msg,
+			path: [storeName]
+		});
+		children.push(failNode("field", "autoIncrement", `${storePath}.autoIncrement`, "type_mismatch", msg, contractAI, actualAI));
+	} else if (contractAI) children.push(passNode("field", "autoIncrement", `${storePath}.autoIncrement`));
+	const contractIndexes = contractStore.indexes ?? {};
+	const actualIndexes = actualStore.indexes ?? {};
+	for (const [indexName, contractIndex] of Object.entries(contractIndexes)) {
+		const actualIndex = actualIndexes[indexName];
+		children.push(verifyIndex(indexName, contractIndex, actualIndex, storeName, storePath, issues));
+	}
+	for (const indexName of Object.keys(actualIndexes)) if (!(indexName in contractIndexes)) {
+		const msg = `Index "${indexName}" exists in manifest but is not in contract`;
+		if (strict) {
+			issues.push({
+				kind: "extra_index",
+				table: storeName,
+				indexOrConstraint: indexName,
+				message: msg,
+				path: [storeName, indexName]
+			});
+			children.push(failNode("index", indexName, `${storePath}.indexes.${indexName}`, "extra_index", msg, void 0, actualIndexes[indexName]));
+		} else children.push(warnNode("index", indexName, `${storePath}.indexes.${indexName}`, "extra_index", msg, void 0, actualIndexes[indexName]));
+	}
+	if (children.some((c) => c.status === "fail")) return failNode("collection", storeName, storePath, "schema_mismatch", `Store "${storeName}" has schema issues`, null, null, children);
+	if (children.some((c) => c.status === "warn")) return {
+		status: "warn",
+		kind: "collection",
+		name: storeName,
+		contractPath: storePath,
+		code: "ok",
+		message: `Store "${storeName}" has warnings`,
+		expected: null,
+		actual: null,
+		children
+	};
+	return passNode("collection", storeName, storePath, children);
+}
+/**
+* Pure, synchronous schema verification for IndexedDB.
+*
+* Compares the stores and indexes defined in the contract against the manifest
+* schema (which represents the actual IndexedDB database). Returns a
+* {@link VerifyDatabaseSchemaResult} that callers can inspect for issues.
+*
+* Does not perform any I/O — all inputs must already be available.
+*
+* @param contract   - Validated IDB contract (what we expect the schema to be).
+* @param schema     - Schema IR from the manifest (what the schema actually is).
+* @param strict     - When `true`, extra stores/indexes in the manifest are failures.
+* @param options    - Optional context paths for metadata / error reporting.
+*/
+function verifyIdbSchema(contract, schema, strict) {
+	const start = Date.now();
+	const issues = [];
+	const storeNodes = [];
+	const contractStores = contract.storage.stores;
+	const actualStores = schema.stores;
+	for (const [storeName, contractStore] of Object.entries(contractStores)) {
+		const actualStore = actualStores[storeName];
+		storeNodes.push(verifyStore(storeName, contractStore, actualStore, strict, issues));
+	}
+	for (const [storeName, actualStore] of Object.entries(actualStores)) if (!(storeName in contractStores)) {
+		const msg = `Object store "${storeName}" exists in manifest but is not in contract`;
+		if (strict) {
+			issues.push({
+				kind: "extra_table",
+				table: storeName,
+				message: msg,
+				path: [storeName]
+			});
+			storeNodes.push(failNode("collection", storeName, `storage.stores.${storeName}`, "extra_table", msg, void 0, actualStore));
+		} else storeNodes.push(warnNode("collection", storeName, `storage.stores.${storeName}`, "extra_table", msg, void 0, actualStore));
+	}
+	const root = {
+		status: storeNodes.some((n) => n.status === "fail") ? "fail" : storeNodes.some((n) => n.status === "warn") ? "warn" : "pass",
+		kind: "root",
+		name: "idb",
+		contractPath: "storage.stores",
+		code: issues.length === 0 ? "ok" : "schema_mismatch",
+		message: issues.length === 0 ? "All stores and indexes match" : `${issues.length} schema issue(s) found`,
+		expected: null,
+		actual: null,
+		children: storeNodes
+	};
+	const counts = countStatuses([root, ...storeNodes]);
+	const ok = root.status !== "fail";
+	const storageHash = contract.storage.storageHash;
+	const profileHash = contract.profileHash;
+	const contractField = profileHash !== void 0 ? {
+		storageHash,
+		profileHash
+	} : { storageHash };
+	const metaField = { strict };
+	const sharedResult = {
+		summary: ok ? "Schema verification passed" : `Schema verification failed: ${issues.length} issue(s)`,
+		contract: contractField,
+		target: { expected: "idb" },
+		schema: {
+			issues,
+			root,
+			counts
+		},
+		meta: metaField,
+		timings: { total: Date.now() - start }
+	};
+	if (ok) return {
+		ok: true,
+		...sharedResult
+	};
+	return {
+		ok: false,
+		code: VERIFY_CODE_SCHEMA_FAILURE,
+		...sharedResult
+	};
+}
+//#endregion
+//#region src/core/control-instance.ts
+const REFUSAL_CODE = "IDB-CLI-UNSUPPORTED";
+/**
+* Single-string refusal message baked into `summary` because the framework
+* `VerifyDatabaseResult` / `SignDatabaseResult` `meta` field is strict-shaped
+* (`{ contractPath, configPath? }`) and doesn't accept extra explanation
+* fields. The summary is the only free-form text field on every result.
+*/
+function refusalSummary(action) {
+	return `IndexedDB cannot be ${action} from the CLI. IndexedDB only exists in the browser; the CLI runs in Node.js, so there is no live database for it to inspect or update. Author migrations with \`prisma-idb migration plan\`, validate the chain with \`prisma-idb migration preflight\`, and let \`createAutoMigratingIdbClient\` apply them the next time the app opens in a browser.`;
+}
+function contractInfo(storageHash, profileHash) {
+	return profileHash !== void 0 ? {
+		storageHash,
+		profileHash
+	} : { storageHash };
+}
+function verifyMeta(contractPath, configPath) {
+	return configPath !== void 0 ? {
+		contractPath,
+		configPath
+	} : { contractPath };
+}
+function signMeta(contractPath, configPath) {
+	return configPath !== void 0 ? {
+		contractPath,
+		configPath
+	} : { contractPath };
+}
+/**
+* Creates an IDB control family instance for the given control stack.
+*
+* **CLI surface — refusals**: IndexedDB is a browser API, so the CLI cannot
+* read or write the live database. Every method that would normally talk to a
+* database (`verify`, `sign`, `readMarker`, `readAllMarkers`, `introspect`)
+* returns a structured refusal pointing the user at the contract-space
+* authoring + preflight workflow.
+*
+* The CLI-side `db init`, `db update`, and `db verify` commands therefore
+* surface a uniform `IDB-CLI-UNSUPPORTED` envelope rather than silently
+* succeeding.
+*
+* **Active surface**: `deserializeContract` (pure) and `verifySchema` (pure
+* function over an in-memory `IdbSchemaIR`) continue to work — neither
+* needs a live database.
+*
+* @param _stack - The assembled control stack (unused; IDB has no adapter/extension layer).
+*/
+function createIdbFamilyInstance(_stack) {
+	return {
+		familyId: "idb",
+		deserializeContract(contractJson) {
+			return validateContract(contractJson);
+		},
+		async verify(options) {
+			const start = Date.now();
+			const contract = validateContract(options.contract);
+			const storageHash = contract.storage.storageHash;
+			const profileHash = contract.profileHash;
+			if (options.expectedTargetId !== "idb") return {
+				ok: false,
+				code: VERIFY_CODE_TARGET_MISMATCH,
+				summary: `Target mismatch: expected "idb", got "${options.expectedTargetId}"`,
+				contract: contractInfo(storageHash, profileHash),
+				target: {
+					expected: options.expectedTargetId,
+					actual: "idb"
+				},
+				meta: verifyMeta(options.contractPath, options.configPath),
+				timings: { total: Date.now() - start }
+			};
+			return {
+				ok: false,
+				code: REFUSAL_CODE,
+				summary: refusalSummary("verified"),
+				contract: contractInfo(storageHash, profileHash),
+				target: {
+					expected: "idb",
+					actual: "idb"
+				},
+				meta: verifyMeta(options.contractPath, options.configPath),
+				timings: { total: Date.now() - start }
+			};
+		},
+		verifySchema(options) {
+			return verifyIdbSchema(validateContract(options.contract), options.schema, options.strict);
+		},
+		async sign(options) {
+			const start = Date.now();
+			const contract = validateContract(options.contract);
+			const storageHash = contract.storage.storageHash;
+			const profileHash = contract.profileHash ?? "";
+			return {
+				ok: false,
+				summary: refusalSummary("signed"),
+				contract: contractInfo(storageHash, profileHash),
+				target: {
+					expected: "idb",
+					actual: "idb"
+				},
+				marker: {
+					created: false,
+					updated: false
+				},
+				meta: signMeta(options.contractPath, options.configPath),
+				timings: { total: Date.now() - start }
+			};
+		},
+		async readMarker(_options) {
+			return null;
+		},
+		async readAllMarkers(_options) {
+			return /* @__PURE__ */ new Map();
+		},
+		async readLedger(_options) {
+			return [];
+		},
+		async introspect(_options) {
+			return { stores: {} };
+		}
+	};
+}
+//#endregion
+//#region src/core/control-descriptor.ts
+/**
+* IDB family descriptor — the control-plane entry point for the IDB family.
+*
+* Registered in a Prisma 8 config file under the `family` key:
+* ```ts
+* import idb from '@prisma-idb/family-idb/control';
+* export default defineConfig({ family: idb, ... });
+* ```
+*
+* **Responsibilities:**
+* - Carries the {@link idbEmission} plugin used by `prisma contract emit`
+*   to generate `contract.d.ts`.
+* - Acts as a factory: `create(stack)` returns an {@link IdbControlFamilyInstance}
+*   with domain-action methods consumed by the CLI.
+*/
+var IdbFamilyDescriptor = class {
+	kind = "family";
+	id = "idb";
+	familyId = "idb";
+	version = "0.0.1";
+	emission = idbEmission;
+	/**
+	* Creates an {@link IdbControlFamilyInstance} for the given control stack.
+	*
+	* The instance is a plain object whose methods implement the CLI domain
+	* actions (validateContract, verify, sign, etc.).
+	*/
+	create(stack) {
+		return createIdbFamilyInstance(stack);
+	}
+};
+//#endregion
+//#region src/exports/control.ts
+var control_default = new IdbFamilyDescriptor();
+//#endregion
+export { control_default as default };
+
+//# sourceMappingURL=control.mjs.map