@happyvertical/smrt-core 0.49.3 → 0.49.5

package/dist/object.js

@@ -1,7 +1,7 @@
 import { classifyDatabaseError, classifyDialectMessage } from "./db-errors.js";
 import { DatabaseError, ErrorUtils, RuntimeError, SmrtError, TenantIsolationError, ValidationError } from "./errors.js";
 import { toSnakeCase } from "./utils/naming.js";
-import { runCascadeDelete } from "./cascade.js";
+import { buildCascadePlan, cascadeReferencesTo, runCascadeDelete } from "./cascade.js";
 import { broadcastCacheInvalidation, hasCrossProcessCacheInterest, invalidateCollectionCache, resolveDbCacheKey } from "./collection-cache.js";
 import { isEmbeddedDatabase, isPostgresDatabase, usesEmbeddedRevisionFallback, withEmbeddedWriteQueue, withEmbeddedWriteTransaction } from "./embedded-write-queue.js";
 import { GlobalInterceptors, createInterceptorContext, resolveGetStringFilter } from "./interceptors.js";
@@ -11,6 +11,8 @@ import { SmrtClass } from "./class.js";
 import { EmbeddingProvider } from "./embeddings/provider.js";
 import { EmbeddingStorage } from "./embeddings/storage.js";
 import { ContentHasher } from "./embeddings/hash.js";
+import { getBoxedPrimitiveKind, isRawJSON } from "./plain-json.js";
+import { isBatchSafeValidator } from "./registry/validator.js";
 import { resolveOneToManyInverse, resolveRelationshipTargetName } from "./relationship-loader.js";
 import { postgresRevisionCondition } from "./revision-guard.js";
 import { verifyPersistenceTable } from "./schema/table-verifier.js";
@@ -21,9 +23,76 @@ import { createLogger } from "@happyvertical/logger";
 import { buildWhere } from "@happyvertical/sql";
 //#region src/object.ts
 var logger = createLogger({ level: process.env.DEBUG_STI ? "debug" : "info" });
+var nativeJunctionClients = /* @__PURE__ */ new WeakSet();
 function isDuckDbHugeInt(value) {
 	return Boolean(value && typeof value === "object" && "hugeint" in value && (typeof value.hugeint === "number" || typeof value.hugeint === "bigint"));
 }
+var PLAIN_JSON_OMITTED = Symbol("plain-json-omitted");
+/**
+* Materialize the values JSON.stringify() would emit without first encoding
+* them into a string. This keeps toPlainObject() suitable for SvelteKit while
+* avoiding an encode/decode round trip for every model in a collection.
+*/
+function toPlainJSONValue(value, key, ancestors, applyToJSON = true) {
+	if (value === null) return null;
+	let valueType = typeof value;
+	if (applyToJSON && (valueType === "object" || valueType === "function" || valueType === "bigint")) {
+		const toJSON = value.toJSON;
+		if (typeof toJSON === "function") {
+			value = Reflect.apply(toJSON, value, [key]);
+			if (value === null) return null;
+			valueType = typeof value;
+		}
+	}
+	switch (valueType) {
+		case "string":
+		case "boolean": return value;
+		case "number": return Number.isFinite(value) ? value === 0 ? 0 : value : null;
+		case "undefined":
+		case "function":
+		case "symbol": return PLAIN_JSON_OMITTED;
+		case "bigint": throw new TypeError("Do not know how to serialize a BigInt");
+	}
+	const objectValue = value;
+	const isArray = Array.isArray(objectValue);
+	if (!isArray && isRawJSON(objectValue)) return JSON.parse(objectValue.rawJSON);
+	switch (isArray ? void 0 : getBoxedPrimitiveKind(objectValue)) {
+		case "number": {
+			const numberValue = +objectValue;
+			return Number.isFinite(numberValue) ? numberValue === 0 ? 0 : numberValue : null;
+		}
+		case "string": return String(objectValue);
+		case "boolean": return Boolean.prototype.valueOf.call(objectValue);
+		case "bigint": throw new TypeError("Do not know how to serialize a BigInt");
+	}
+	if (ancestors.includes(objectValue)) throw new TypeError("Converting circular structure to JSON");
+	ancestors.push(objectValue);
+	try {
+		if (isArray) {
+			const result = [];
+			const length = Math.min(Math.max(Math.trunc(+objectValue.length) || 0, 0), Number.MAX_SAFE_INTEGER);
+			for (let index = 0; index < length; index++) {
+				const item = toPlainJSONValue(objectValue[index], String(index), ancestors);
+				result.push(item === PLAIN_JSON_OMITTED ? null : item);
+			}
+			return result;
+		}
+		const result = {};
+		for (const property of Object.keys(objectValue)) {
+			const item = toPlainJSONValue(objectValue[property], property, ancestors);
+			if (item !== PLAIN_JSON_OMITTED) if (property === "__proto__") Object.defineProperty(result, property, {
+				configurable: true,
+				enumerable: true,
+				value: item,
+				writable: true
+			});
+			else result[property] = item;
+		}
+		return result;
+	} finally {
+		ancestors.pop();
+	}
+}
 /**
 * Default maximum number of characters of serialized object data injected into
 * the AI prompts built by `is()`, `do()`, and `describe()`.
@@ -780,7 +849,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 	* ```
 	*/
 	toPlainObject() {
-		return JSON.parse(JSON.stringify(this));
+		return toPlainJSONValue(this.toJSON(), "", [], false);
 	}
 	/**
 	* Collect public-serialization field policy in one registry traversal.
@@ -1072,6 +1141,233 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		for (const columnName of uuidColumns) if (data[columnName] === "") data[columnName] = null;
 	}
 	/**
+	* Conservative eligibility for junction batching. Additional methods are fine;
+	* replacing any runtime method/accessor requires the sequential lifecycle.
+	* Re-evaluate for every call: registry and interceptor registration is dynamic.
+	* @internal
+	*/
+	supportsJunctionBatch() {
+		if (!SmrtObject.hasBaseJunctionLifecycle(this)) return false;
+		const name = this.getResolvedQualifiedName();
+		if (ObjectRegistry.getTableStrategy(name) === "sti" || this._insertOnly || !GlobalInterceptors.supportsBulkMutation(this.getResolvedClassName()) || buildCascadePlan(ObjectRegistry, name).references.length > 0 || ObjectRegistry.resolveEmbeddingConfig(this.getResolvedClassName())) return false;
+		const config = this.getRegisteredClassInfo()?.config;
+		if (config?.hooks && Object.keys(config.hooks).length > 0) return false;
+		if (ObjectRegistry.getValidationRules(this.getResolvedClassName()) === void 0 && (ObjectRegistry.getValidators(this.getResolvedClassName()) ?? []).some((validator) => !isBatchSafeValidator(validator))) return false;
+		for (const field of ObjectRegistry.getFields(name).values()) if (field.type === "crossPackageRef" && (field._meta || field).validate) return false;
+		return true;
+	}
+	/** Check overrides before initialization can execute custom model code. */
+	static hasBaseJunctionLifecycle(candidate) {
+		let prototype = candidate;
+		while (prototype && prototype !== SmrtObject.prototype) {
+			for (const key of Object.getOwnPropertyNames(prototype)) {
+				if (key === "constructor") continue;
+				const own = Object.getOwnPropertyDescriptor(prototype, key);
+				if (own?.get || own?.set) return false;
+				let base = SmrtObject.prototype;
+				while (base) {
+					const original = Object.getOwnPropertyDescriptor(base, key);
+					if (original) {
+						if (typeof original.value === "function" && own?.value !== original.value || original.get && own?.get !== original.get || original.set && own?.set !== original.set) return false;
+						break;
+					}
+					base = Object.getPrototypeOf(base);
+				}
+			}
+			prototype = Object.getPrototypeOf(prototype);
+		}
+		return true;
+	}
+	/**
+	* Persist a bounded compatible junction replacement through owned lifecycle
+	* preparation/completion. False means no persistence occurred; callers retain
+	* their virtual per-row path. Unsupported shapes never use raw SQL shortcuts.
+	* @internal
+	*/
+	static async tryJunctionBatch(removed, added) {
+		const all = [...removed, ...added];
+		const first = all[0];
+		if (!first) return true;
+		if (all.length > 100 || all.some((item) => item.db !== first.db || item.tableName !== first.tableName || item.constructor !== first.constructor || !SmrtObject.prototype.supportsJunctionBatch.call(item)) || added.some((item) => item.isPersisted) || removed.some((item) => !item.id)) return false;
+		const dbCapabilities = first.db;
+		if (first.getDatabaseEngineHint() === "json") return false;
+		const duck = first.isNativeDuckDb();
+		if (duck) {
+			const client = dbCapabilities.client;
+			if (!client) return false;
+			if (typeof dbCapabilities.getTableSchema === "function" || first.getDatabaseEngineHint() === "duckdb") nativeJunctionClients.add(client);
+			if (!nativeJunctionClients.has(client)) return false;
+		}
+		const engine = isPostgresDatabase(first.db) ? "postgres" : duck ? "duckdb" : detectEngine(first.db.url ?? "", first.getDatabaseEngineHint());
+		if (![
+			"sqlite",
+			"duckdb",
+			"postgres"
+		].includes(engine)) return false;
+		const prepared = [];
+		try {
+			for (const item of added) prepared.push(await item.prepareSave(void 0));
+		} catch {
+			return false;
+		}
+		const columns = prepared[0] ? Object.keys(prepared[0].data) : [];
+		const conflict = prepared[0]?.conflictColumns ?? [];
+		const identities = /* @__PURE__ */ new Set();
+		if (columns.length * added.length > 900 || prepared.some((entry) => {
+			if (entry.writePlan.type !== "upsert" || JSON.stringify(Object.keys(entry.data)) !== JSON.stringify(columns) || JSON.stringify(entry.conflictColumns) !== JSON.stringify(conflict) || conflict.some((key) => entry.data[key] == null)) return true;
+			const identity = JSON.stringify(conflict.map((key) => entry.data[key]));
+			if (identities.has(identity)) return true;
+			identities.add(identity);
+			return false;
+		})) return false;
+		const deletions = [];
+		for (const instance of removed) {
+			const context = createInterceptorContext(instance.constructor.name, "delete", void 0, void 0, instance.getResolvedQualifiedName());
+			await GlobalInterceptors.executeBeforeDelete(instance, context);
+			await instance.runHook("beforeDelete");
+			await instance.verifyStorageReady();
+			deletions.push({
+				instance,
+				context
+			});
+		}
+		if (!GlobalInterceptors.supportsBulkMutation(first.getResolvedClassName())) return false;
+		if (removed.length > 0) {
+			const cascade = await withEmbeddedWriteTransaction(first.db, isEmbeddedDatabase(first.db), async (db) => {
+				const ids = removed.map((item) => item.id);
+				const result = await cascadeReferencesTo(db, ObjectRegistry, {
+					className: first.getResolvedQualifiedName(),
+					tableName: first.tableName,
+					ids
+				});
+				await db.delete(first.tableName, { "id in": ids });
+				return result;
+			}, true);
+			for (const instance of removed) {
+				instance._persisted = false;
+				instance.invalidateCollectionReadCache();
+				await instance.runHook("afterDelete");
+			}
+			for (const table of cascade.affectedTables) first.invalidateCollectionReadCache(table, cascade.affectedTableClasses.get(table));
+			await GlobalInterceptors.executeBulkAfter("afterDelete", deletions);
+		}
+		if (added.length > 0) {
+			const quote = (identifier) => `"${identifier.replaceAll("\"", "\"\"")}"`;
+			const values = [];
+			const tuples = prepared.map(({ data }) => `(${columns.map((column) => {
+				const value = data[column];
+				values.push(value instanceof Date ? value.toISOString() : value === void 0 ? null : value !== null && typeof value === "object" ? JSON.stringify(value) : typeof value === "boolean" && engine === "sqlite" ? Number(value) : value);
+				return engine === "postgres" ? `$${values.length}` : "?";
+			}).join(", ")})`);
+			const updates = columns.map((column) => `${quote(column)} = excluded.${quote(column)}`).join(", ");
+			const sql = `INSERT INTO ${quote(first.tableName)} (${columns.map(quote).join(", ")}) VALUES ${tuples.join(", ")} ON CONFLICT (${conflict.map(quote).join(", ")}) DO UPDATE SET ${updates}`;
+			await withEmbeddedWriteQueue(first.db, isEmbeddedDatabase(first.db), () => ErrorUtils.withRetry(async () => {
+				try {
+					await first.db.query(sql, ...values);
+				} catch (error) {
+					if (!(error instanceof Error)) throw error;
+					const classification = classifyDatabaseError(error);
+					const field = first.extractConstraintFieldFromChain(error, classification);
+					if (classification.kind === "unique_violation") throw ValidationError.uniqueConstraint(field, first.getFieldValue(field));
+					if (classification.kind === "not_null_violation") throw ValidationError.requiredField(field, first.getResolvedClassName());
+					throw DatabaseError.queryFailed(`UPSERT INTO ${first.tableName}`, error);
+				}
+			}, 3, 500));
+			const completions = [];
+			for (let i = 0; i < added.length; i++) {
+				await added[i].completeSave(prepared[i].interceptorContext, false);
+				completions.push({
+					instance: added[i],
+					context: prepared[i].interceptorContext
+				});
+			}
+			await GlobalInterceptors.executeBulkAfter("afterSave", completions);
+		}
+		return true;
+	}
+	/** Shared preparation for ordinary saves and compatible bulk creates. */
+	async prepareSave(revisionGuard) {
+		const className = this.getResolvedClassName();
+		await this.validateBeforeSave();
+		await this.validateCrossPackageRefs();
+		const interceptorContext = createInterceptorContext(className, "save", void 0, void 0, this.getResolvedQualifiedName());
+		await GlobalInterceptors.executeBeforeSave(this, interceptorContext);
+		if (!this.id) this.id = crypto.randomUUID();
+		if (!this.slug) this.slug = await this.getSlug();
+		this.updated_at = this.nextRevisionTimestamp(revisionGuard);
+		if (!this.created_at) this.created_at = /* @__PURE__ */ new Date();
+		await this.verifyStorageReady();
+		const tableStrategy = ObjectRegistry.getTableStrategy(this.getResolvedQualifiedName());
+		if (process.env.NODE_ENV === "development") {
+			if (this.toJSON !== SmrtObject.prototype.toJSON && tableStrategy === "sti") logger.warn(`[SMRT STI Warning] ${this.constructor.name} overrides toJSON() but uses STI.\nEnsure super.toJSON() is called or _meta_type is set manually.\nThis can cause "Missing _meta_type discriminator" errors.\nPrefer using the transformJSON() hook instead of overriding toJSON().\nSee issue #377: https://github.com/happyvertical/smrt/issues/377`);
+		}
+		if (tableStrategy === "sti") {
+			warnIfSkipRehydrateSet();
+			const qualifiedName = this.getResolvedQualifiedName();
+			const classesNeedingFreshSTIFieldState = Array.from(/* @__PURE__ */ new Set([qualifiedName, ...getSTIHierarchyMembers(qualifiedName)]));
+			for (const stiClassName of classesNeedingFreshSTIFieldState) await ObjectRegistry.getAllFields(stiClassName);
+		}
+		const jsonData = this.toJSON();
+		if (tableStrategy === "sti") {
+			if (!jsonData._meta_type) throw new Error(`STI validation failed: Missing _meta_type discriminator when saving ${className}. This should have been set automatically by toJSON(). Please report this bug.`);
+			if (!isValidMetaType(jsonData._meta_type, className)) throw new Error(`STI validation failed: _meta_type mismatch when saving ${className}. Expected '${getExpectedMetaType(className)}' but got '${jsonData._meta_type}'. This should not happen - please report this bug.`);
+		}
+		const data = {};
+		for (const [key, value] of Object.entries(jsonData)) if (key.startsWith("_")) data[key] = value;
+		else data[toSnakeCase(key)] = value;
+		data.updated_at = this.updated_at;
+		await this.coerceEmptyUuidValuesToNull(className, data);
+		const conflictColumns = ObjectRegistry.getConflictColumns(className);
+		const derivedColumns = this.getPersistenceDerivedColumns();
+		const registeredFields = ObjectRegistry.getFields(className);
+		const registeredColumns = new Set([...registeredFields].filter(([, field]) => field.type !== "oneToMany" && field.type !== "manyToMany").map(([name]) => toSnakeCase(name)));
+		const protectedColumns = /* @__PURE__ */ new Set([
+			"id",
+			"slug",
+			"tenant_id",
+			"created_at",
+			"updated_at",
+			"_meta_type",
+			"_meta_data",
+			...conflictColumns.map(toSnakeCase)
+		]);
+		for (const [name, field] of registeredFields) if (field.__tenancy?.isTenantIdField || field._meta?.__tenancy?.isTenantIdField) protectedColumns.add(toSnakeCase(name));
+		for (const column of derivedColumns) if (!registeredColumns.has(column) || protectedColumns.has(column)) throw RuntimeError.invalidState(`Invalid persistence derived column declaration: ${column}`, {
+			className,
+			column
+		});
+		const normalizedColumns = this.normalizePersistenceData(Object.freeze({ ...data }));
+		if (normalizedColumns) {
+			for (const column of Object.keys(normalizedColumns)) if (!derivedColumns.includes(column)) throw RuntimeError.invalidState(`Undeclared persistence derived column: ${column}`, {
+				className,
+				column
+			});
+			Object.assign(data, normalizedColumns);
+		}
+		return {
+			interceptorContext,
+			data,
+			writePlan: await this.planPersistenceWrite(className, tableStrategy, data, conflictColumns),
+			conflictColumns
+		};
+	}
+	async completeSave(interceptorContext, runInterceptors = true) {
+		const className = this.getResolvedClassName();
+		this._persisted = true;
+		this.invalidateCollectionReadCache();
+		if (runInterceptors) await GlobalInterceptors.executeAfterSave(this, interceptorContext);
+		const embeddingConfig = ObjectRegistry.resolveEmbeddingConfig(className);
+		const skipAutoEmbeddings = this.options._skipAutoEmbeddings === true;
+		if (embeddingConfig && embeddingConfig.autoGenerate !== false && !skipAutoEmbeddings) {
+			if (await this.getOptionalAiClient()) {
+				if (await this.hasStaleEmbeddings()) this.generateEmbeddings().catch((error) => {
+					logger.warn(`Failed to auto-generate embeddings for ${this.constructor.name}`, { error: error instanceof Error ? error.message : error });
+				});
+			}
+		}
+		if (skipAutoEmbeddings) this.options._skipAutoEmbeddings = false;
+	}
+	/**
 	* Persists this object to the database using an upsert (insert or update).
 	*
 	* Steps performed on every save:
@@ -1131,37 +1427,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		const revisionGuard = loadedRevision instanceof Date ? loadedRevision.toISOString() : loadedRevision;
 		try {
 			if (expectedUpdatedAt !== void 0 && (!this._persisted || !this.id)) throw RuntimeError.invalidState("A revision-guarded save requires a persisted object", { className });
-			await this.validateBeforeSave();
-			await this.validateCrossPackageRefs();
-			const interceptorContext = createInterceptorContext(className, "save", void 0, void 0, this.getResolvedQualifiedName());
-			await GlobalInterceptors.executeBeforeSave(this, interceptorContext);
-			if (!this.id) this.id = crypto.randomUUID();
-			if (!this.slug) this.slug = await this.getSlug();
-			this.updated_at = this.nextRevisionTimestamp(revisionGuard);
-			if (!this.created_at) this.created_at = /* @__PURE__ */ new Date();
-			await this.verifyStorageReady();
-			const tableStrategy = ObjectRegistry.getTableStrategy(this.getResolvedQualifiedName());
-			if (process.env.NODE_ENV === "development") {
-				if (this.toJSON !== SmrtObject.prototype.toJSON && tableStrategy === "sti") logger.warn(`[SMRT STI Warning] ${this.constructor.name} overrides toJSON() but uses STI.\nEnsure super.toJSON() is called or _meta_type is set manually.\nThis can cause "Missing _meta_type discriminator" errors.\nPrefer using the transformJSON() hook instead of overriding toJSON().\nSee issue #377: https://github.com/happyvertical/smrt/issues/377`);
-			}
-			if (tableStrategy === "sti") {
-				warnIfSkipRehydrateSet();
-				const qualifiedName = this.getResolvedQualifiedName();
-				const classesNeedingFreshSTIFieldState = Array.from(/* @__PURE__ */ new Set([qualifiedName, ...getSTIHierarchyMembers(qualifiedName)]));
-				for (const stiClassName of classesNeedingFreshSTIFieldState) await ObjectRegistry.getAllFields(stiClassName);
-			}
-			const jsonData = this.toJSON();
-			if (tableStrategy === "sti") {
-				if (!jsonData._meta_type) throw new Error(`STI validation failed: Missing _meta_type discriminator when saving ${className}. This should have been set automatically by toJSON(). Please report this bug.`);
-				if (!isValidMetaType(jsonData._meta_type, className)) throw new Error(`STI validation failed: _meta_type mismatch when saving ${className}. Expected '${getExpectedMetaType(className)}' but got '${jsonData._meta_type}'. This should not happen - please report this bug.`);
-			}
-			const data = {};
-			for (const [key, value] of Object.entries(jsonData)) if (key.startsWith("_")) data[key] = value;
-			else data[toSnakeCase(key)] = value;
-			data.updated_at = this.updated_at;
-			await this.coerceEmptyUuidValuesToNull(className, data);
-			const conflictColumns = ObjectRegistry.getConflictColumns(className);
-			const writePlan = await this.planPersistenceWrite(className, tableStrategy, data, conflictColumns);
+			const { interceptorContext, data, writePlan, conflictColumns } = await this.prepareSave(revisionGuard);
 			const upsertConflictColumns = this._persisted && data.id ? ["id"] : conflictColumns;
 			const useEmbeddedRevisionFallback = revisionGuard !== void 0 && usesEmbeddedRevisionFallback(this.db);
 			const serializeEmbeddedWrite = isEmbeddedDatabase(this.db);
@@ -1210,19 +1476,7 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 				id: this.id
 			});
 			revisionPersisted = true;
-			this._persisted = true;
-			this.invalidateCollectionReadCache();
-			await GlobalInterceptors.executeAfterSave(this, interceptorContext);
-			const embeddingConfig = ObjectRegistry.resolveEmbeddingConfig(className);
-			const skipAutoEmbeddings = this.options._skipAutoEmbeddings === true;
-			if (embeddingConfig && embeddingConfig.autoGenerate !== false && !skipAutoEmbeddings) {
-				if (await this.getOptionalAiClient()) {
-					if (await this.hasStaleEmbeddings()) this.generateEmbeddings().catch((error) => {
-						logger.warn(`Failed to auto-generate embeddings for ${this.constructor.name}`, { error: error instanceof Error ? error.message : error });
-					});
-				}
-			}
-			if (skipAutoEmbeddings) this.options._skipAutoEmbeddings = false;
+			await this.completeSave(interceptorContext);
 			return this;
 		} catch (error) {
 			if (!revisionPersisted) this.updated_at = previousUpdatedAt;
@@ -1346,6 +1600,22 @@ var SmrtObject = class SmrtObject extends SmrtClass {
 		const name = candidate?.name;
 		return name === "TenantIsolationError" || name === "TenantContextError";
 	}
+	/** Declare permitted snake-case derived schema columns; preserve super entries. */
+	getPersistenceDerivedColumns() {
+		return [];
+	}
+	/**
+	* Return derived schema-column values for the final persistence row.
+	* Runs synchronously after beforeSave, the complete toJSON/transformJSON
+	* chain, snake-case mapping and UUID coercion; returned columns are merged
+	* before every save branch. This does not change public serialization.
+	* Only derive columns from this read-only snapshot: do not modify source,
+	* identity, tenant or revision columns, and do not perform I/O. Overrides
+	* should preserve any columns returned by super. Declare permitted snake-case
+	* schema columns in getPersistenceDerivedColumns(), preserving super entries.
+	* Framework identity, tenant, revision and conflict columns cannot be declared.
+	*/
+	normalizePersistenceData(_data) {}
 	/**
 	* Validates object state before saving
 	* Override in subclasses to add custom validation logic