joist-core 2.3.0 → 2.4.0

package/build/drivers/Driver.d.mts

@@ -0,0 +1,51 @@
+import { JoinRowTodo, Todo } from "../flush/Todo.mjs";
+import { ParsedFindQuery } from "../queries/find/QueryParser.mjs";
+import { RowData } from "../RowData.mjs";
+import { PreloadPlugin } from "../plugins/PreloadPlugin.mjs";
+import { EntityManager } from "../EntityManager.mjs";
+//#region src/drivers/Driver.d.ts
+/**
+ * Isolates all SQL calls that Joist needs to make to fetch/save data.
+ *
+ * @typeParam TX - the connection library-specific `Transaction` type, i.e. `Knex.Transaction`
+ */
+interface Driver<TX = unknown> {
+  /** Executes a low-level `ParsedFindQuery` against the database and returns the rows. */
+  executeFind(em: EntityManager, parsed: ParsedFindQuery, settings: {
+    limit?: number;
+    offset?: number;
+  }): Promise<any[]>;
+  /**
+   * Executes a raw SQL query with bindings and returns its command count and rows.
+   *
+   * The count is reported by the database command, never inferred from the returned rows.
+   * Commands without a count, such as DDL, return null; `em.execute` requires a nonnegative integer.
+   */
+  executeQuery(em: EntityManager, sql: string, bindings: any[]): Promise<DriverQueryResult>;
+  /**
+   * Like `executeFind`, but returns a lazy {@link RowData} instead of materialized POJO rows.
+   *
+   * This method's *presence* is the capability signal: drivers define it only when lazy rows
+   * are supported + enabled (i.e. `PostgresDriver` with `lazyRows: true`), and entity-hydrating
+   * loaders fall back to classic rows wrapped in a `PojoRowData` when it is undefined.
+   */
+  executeFindRowData?(em: EntityManager, parsed: ParsedFindQuery, settings: {
+    limit?: number;
+    offset?: number;
+  }): Promise<RowData>;
+  transaction<T>(em: EntityManager, fn: (txn: TX) => Promise<T>): Promise<T>;
+  assignNewIds(em: EntityManager, todos: Record<string, Todo>): Promise<void>;
+  flush(em: EntityManager, todos: Record<string, Todo>, joinRows: Record<string, JoinRowTodo>): Promise<void>;
+  /** Allows the driver to opt `EntityManager`s into plugins it has enabled/supported by default. */
+  defaultPlugins: {
+    preloadPlugin?: PreloadPlugin;
+  };
+}
+/** Raw rows and the database command's affected-row count for mutations or selected-row count for reads. */
+interface DriverQueryResult {
+  rowCount: number | null;
+  rows: any[];
+}
+//#endregion
+export { Driver, DriverQueryResult };
+//# sourceMappingURL=Driver.d.mts.map

package/build/drivers/Driver.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Driver.d.mts","names":[],"sources":["../../src/drivers/Driver.ts"],"mappings":";;;;;;;;;;;UAWiB,OAAO;;EAEtB,YACE,IAAI,eACJ,QAAQ,iBACR;IAAY;IAAgB;MAC3B;;;;;;;EAQH,aAAa,IAAI,eAAe,aAAa,kBAAkB,QAAQ;;;;;;;;EASvE,oBACE,IAAI,eACJ,QAAQ,iBACR;IAAY;IAAgB;MAC3B,QAAQ;EAEX,YAAY,GAAG,IAAI,eAAe,KAAK,KAAK,OAAO,QAAQ,KAAK,QAAQ;EAExE,aAAa,IAAI,eAAe,OAAO,eAAe,QAAQ;EAE9D,MAAM,IAAI,eAAe,OAAO,eAAe,OAAO,UAAU,eAAe,eAAe;;EAG9F;IAAkB,gBAAgB;;;;UAInB;EACf;EACA"}

package/build/drivers/Driver.js

@@ -1,3 +1,3 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
-//# sourceMappingURL=Driver.js.map
+import "../plugins/PreloadPlugin.js";
+import "../EntityManager.js";
+export {};

package/build/drivers/EntityWriter.cjs

@@ -0,0 +1,208 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+const require_fields = require("../fields.cjs");
+const require_keys = require("../keys.cjs");
+const require_utils = require("../utils.cjs");
+const require_serde_fieldSerde = require("../serde/fieldSerde.cjs");
+const require_EntityMetadata = require("../EntityMetadata.cjs");
+require("../Entity.cjs");
+const require_BaseEntity = require("../BaseEntity.cjs");
+//#region src/drivers/EntityWriter.ts
+/**
+* Builds AST-ish `Ops` for the inserts/updates/deletes in `todos`.
+*
+* This helps decouple the database-specific driver/library from the knowledge
+* of turning entities into table operations, i.e. so they can be unaware of
+* complexities like field -> column mapping, oplocks, and class table inheritance.
+*
+* We still assume Postgres b/c we assume all ids have been pre-assigned for INSERTs,
+* and don't do any topological sorting of cross-row FK dependencies.
+*
+* But this should let us experiment with knex vs. raw client/etc.
+*/
+function generateOps(todos) {
+	const ops = {
+		inserts: [],
+		updates: [],
+		deletes: []
+	};
+	const fixups = [];
+	const sorted = Object.values(todos).sort((a, b) => (a.metadata.nonDeferredFkOrder ?? 0) - (b.metadata.nonDeferredFkOrder ?? 0));
+	for (const todo of sorted) {
+		addInserts(ops, todo, fixups);
+		addUpdates(ops, todo);
+		addDeletes(ops, todo);
+	}
+	if (fixups.length > 0) translateFixupsIntoUpdates(ops, fixups);
+	return ops;
+}
+function addInserts(ops, todo, fixups) {
+	if (todo.inserts.length > 0) {
+		const meta = todo.metadata;
+		if (meta.subTypes.length > 0) {
+			if (meta.inheritanceType === "cti") for (const [meta, group] of groupEntitiesByTable(todo.inserts)) ops.inserts.push(newInsertOp(meta, group, fixups));
+			else if (meta.inheritanceType === "sti") for (const group of require_utils.groupBy(todo.inserts, (e) => require_EntityMetadata.getMetadata(e)).values()) ops.inserts.push(newStiInsertOp(meta, group, fixups));
+			else throw new Error(`Found ${meta.tableName} subTypes without a known inheritanceType ${meta.inheritanceType}`);
+		} else ops.inserts.push(newInsertOp(meta, todo.inserts, fixups));
+	}
+}
+function newInsertOp(meta, entities, fixups) {
+	const columns = Object.values(meta.fields).filter(require_serde_fieldSerde.hasSerde).flatMap((f) => f.serde.columns);
+	const columnValues = collectBindings(entities, meta.tableName, columns, fixups);
+	return {
+		tableName: meta.tableName,
+		columns,
+		columnValues
+	};
+}
+function newStiInsertOp(root, entities, fixups) {
+	const columns = Object.values(require_EntityMetadata.getMetadata(entities[0]).allFields).filter(require_serde_fieldSerde.hasSerde).flatMap((f) => f.serde.columns);
+	const columnValues = collectBindings(entities, root.tableName, columns, fixups);
+	return {
+		tableName: root.tableName,
+		columns,
+		columnValues
+	};
+}
+function addUpdates(ops, todo) {
+	if (todo.updates.length > 0) {
+		const meta = todo.metadata;
+		if (meta.subTypes.length > 0) {
+			if (meta.inheritanceType === "cti") for (const [meta, group] of groupEntitiesByTable(todo.updates)) {
+				const op = newUpdateOp(meta, group);
+				if (op) ops.updates.push(op);
+				addLazyUpdates(ops, meta, group);
+			}
+			else if (meta.inheritanceType === "sti") {
+				const op = newUpdateOp(meta, todo.updates);
+				if (op) ops.updates.push(op);
+				addLazyUpdates(ops, meta, todo.updates);
+			} else throw new Error(`Found ${meta.tableName} subTypes without a known inheritanceType ${meta.inheritanceType}`);
+		} else {
+			const op = newUpdateOp(meta, todo.updates);
+			if (op) ops.updates.push(op);
+			addLazyUpdates(ops, meta, todo.updates);
+		}
+	}
+}
+/**
+* Writes changed `lazy` columns via a targeted `UPDATE table SET lazy_col = ... WHERE id in (...)`.
+*
+* Lazy columns are excluded from the main batch UPDATE (which spans the batch's union of changed fields),
+* so that entities in the batch that never loaded a lazy column keep their existing db value instead of
+* being overwritten with null. Here we write each lazy column only for the entities that actually changed it.
+*/
+function addLazyUpdates(ops, meta, entities) {
+	const idColumn = meta.fields["id"].serde.columns[0];
+	for (const fieldName of meta.lazyFieldNames) {
+		const field = meta.fields[fieldName];
+		if (!require_serde_fieldSerde.hasSerde(field)) continue;
+		const changed = entities.filter((e) => fieldName in require_BaseEntity.getInstanceData(e).changedData);
+		if (changed.length === 0) continue;
+		const columns = [idColumn, ...field.serde.columns];
+		const columnValues = collectBindings(changed, meta.tableName, columns, void 0);
+		ops.updates.push({
+			tableName: meta.tableName,
+			columns,
+			columnValues,
+			updatedAt: void 0
+		});
+	}
+}
+function newUpdateOp(meta, entities) {
+	const changedFields = /* @__PURE__ */ new Set();
+	for (const entity of entities) for (const fieldName in require_BaseEntity.getInstanceData(entity).changedData) changedFields.add(fieldName);
+	if (changedFields.size === 0 && !entities.some((e) => require_BaseEntity.getInstanceData(e).isTouched)) return;
+	const updatedAt = meta.timestampFields?.updatedAt;
+	changedFields.add("id");
+	if (updatedAt) changedFields.add(updatedAt);
+	const lazyFieldNames = meta.lazyFieldNames;
+	for (const entity of entities) {
+		const { data } = require_BaseEntity.getInstanceData(entity);
+		for (const key of changedFields) if (!(key in data) && require_fields.isChangeableField(entity, key) && !lazyFieldNames.has(key)) require_fields.getField(entity, key);
+	}
+	const columns = (meta.inheritanceType === "sti" ? require_EntityMetadata.getBaseSelfAndSubMetas(meta).flatMap((meta) => meta.stiDiscriminatorField ? Object.values(meta.fields) : Object.values(meta.fields).filter((f) => f.fieldName !== "id")) : Object.values(meta.fields)).filter((f) => changedFields.has(f.fieldName)).filter((f) => !lazyFieldNames.has(f.fieldName)).filter(require_serde_fieldSerde.hasSerde).flatMap((f) => f.serde.columns);
+	if (columns.length === 1) return;
+	if (updatedAt) {
+		const serde = meta.fields[updatedAt].serde;
+		columns.push({
+			columnName: "__original_updated_at",
+			dbType: "timestamptz",
+			dbValue: (_, entity) => serde.dbValue(require_BaseEntity.getInstanceData(entity).originalData)
+		});
+	}
+	const columnValues = collectBindings(entities, meta.tableName, columns, []);
+	const updatedAtColumn = updatedAt ? meta.fields[updatedAt].serde.columns[0] : void 0;
+	return {
+		tableName: meta.tableName,
+		columns,
+		updatedAt: updatedAtColumn?.columnName,
+		columnValues
+	};
+}
+function addDeletes(ops, todo) {
+	if (todo.deletes.length > 0) {
+		const meta = todo.metadata;
+		const ids = todo.deletes.map((e) => require_keys.keyToNumber(meta, e.idTagged).toString());
+		if (meta.subTypes.length > 0) require_EntityMetadata.getBaseSelfAndSubMetas(meta).forEach((meta) => {
+			ops.deletes.push({
+				tableName: meta.tableName,
+				ids
+			});
+		});
+		else ops.deletes.push({
+			tableName: meta.tableName,
+			ids
+		});
+	}
+}
+function groupEntitiesByTable(entities) {
+	const entitiesByType = /* @__PURE__ */ new Map();
+	for (const e of entities) for (const m of require_EntityMetadata.getBaseAndSelfMetas(require_EntityMetadata.getMetadata(e))) {
+		let list = entitiesByType.get(m);
+		if (!list) {
+			list = [];
+			entitiesByType.set(m, list);
+		}
+		list.push(e);
+	}
+	return [...entitiesByType.entries()];
+}
+/**
+* Builds a *columnar* array of bindings for the given `entities` and `columns`.
+*
+* We use a columnar approach, instead of `rows[]`, to best match the unnest-based
+* column operations in our `batchInsert` / `batchUpdate` SQL statements.
+*/
+function collectBindings(entities, tableName, columns, fixups) {
+	const entityCount = entities.length;
+	const bindings = new Array(columns.length);
+	const entitiesWithData = entities;
+	const entityData = new Array(entityCount);
+	for (let i = 0; i < entityCount; i++) entityData[i] = entitiesWithData[i].__data.data;
+	for (let columnIndex = 0; columnIndex < columns.length; columnIndex++) {
+		const column = columns[columnIndex];
+		const columnValues = new Array(entityCount);
+		for (let entityIndex = 0; entityIndex < entityCount; entityIndex++) columnValues[entityIndex] = column.dbValue(entityData[entityIndex], entities[entityIndex], tableName, fixups) ?? null;
+		bindings[columnIndex] = columnValues;
+	}
+	return bindings;
+}
+/**
+* Given `fixups` that indicate where we inserted `NULL` into non-deferred FKs, create `UPDATE`s
+* that insert the value now that the FK check will succeed.
+*/
+function translateFixupsIntoUpdates(ops, fixups) {
+	require_utils.groupBy(fixups, (f) => `${f.tableName}.${f.column.columnName}`).forEach((fixups) => {
+		const { tableName, entity, column } = fixups[0];
+		ops.updates.push({
+			tableName,
+			columns: [require_EntityMetadata.getMetadata(entity).fields["id"].serde.columns[0], column],
+			columnValues: [fixups.map((fixup) => fixup.entity.id), fixups.map((fixup) => fixup.value)],
+			updatedAt: void 0
+		});
+	});
+}
+//#endregion
+exports.generateOps = generateOps;
+
+//# sourceMappingURL=EntityWriter.cjs.map

package/build/drivers/EntityWriter.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityWriter.cjs","names":["groupBy","getMetadata","hasSerde","getInstanceData","isChangeableField","getBaseSelfAndSubMetas","keyToNumber","getBaseAndSelfMetas"],"sources":["../../src/drivers/EntityWriter.ts"],"sourcesContent":["import { getInstanceData } from \"src/BaseEntity.ts\";\nimport { type Entity } from \"src/Entity.ts\";\nimport {\n  type EntityMetadata,\n  type Field,\n  type PrimitiveField,\n  getBaseAndSelfMetas,\n  getBaseSelfAndSubMetas,\n  getMetadata,\n} from \"src/EntityMetadata.ts\";\nimport { getField, isChangeableField } from \"src/fields.ts\";\nimport type { Todo } from \"src/flush/Todo.ts\";\nimport { keyToNumber } from \"src/keys.ts\";\nimport { type FieldColumn, type TimestampSerde, hasSerde } from \"src/serde/fieldSerde.ts\";\nimport { groupBy } from \"src/utils.ts\";\n\n/** A simplified view of columns, with only the keys necessary to create SQL statements. */\nexport type OpColumn = { columnName: string; dbType: string; isNullableArray?: boolean };\nexport type InsertOp = { tableName: string; columns: OpColumn[]; columnValues: any[][] };\n/**\n * A logical `update` operation.\n *\n * If we're using op locks, `columns` will include both the new `updatedAt` value (as bumped\n * by the `EntityManager` on mutate), as well as an extra/last \"original updated at\" column\n * (with respective pre-update values in the `rows` data), for including in the conditional\n * update clause.\n */\nexport type UpdateOp = {\n  tableName: string;\n  columns: OpColumn[];\n  columnValues: any[][];\n  updatedAt: string | undefined;\n};\nexport type DeleteOp = { tableName: string; ids: any[] };\n\ntype Ops = { inserts: InsertOp[]; updates: UpdateOp[]; deletes: DeleteOp[] };\n\n/**\n * In schemas with entity FK cycles, we may insert a dummy/null value, and later fix it up\n * before the transaction commits.\n *\n * I.e. `INSERT author.favorite_book_id` as `NULL` and then later do an `UPDATE author\n * SET favorite_book_id = 1` after the book has been inserted/we have the id.\n */\nexport type InsertFixup = {\n  entity: Entity;\n  tableName: string;\n  column: OpColumn;\n  value: any;\n};\n\n/**\n * Builds AST-ish `Ops` for the inserts/updates/deletes in `todos`.\n *\n * This helps decouple the database-specific driver/library from the knowledge\n * of turning entities into table operations, i.e. so they can be unaware of\n * complexities like field -> column mapping, oplocks, and class table inheritance.\n *\n * We still assume Postgres b/c we assume all ids have been pre-assigned for INSERTs,\n * and don't do any topological sorting of cross-row FK dependencies.\n *\n * But this should let us experiment with knex vs. raw client/etc.\n */\nexport function generateOps(todos: Record<string, Todo>): Ops {\n  const ops: Ops = { inserts: [], updates: [], deletes: [] };\n  const fixups: InsertFixup[] = [];\n  // Would be nice to conditionally sort\n  const sorted = Object.values(todos).sort(\n    (a, b) => (a.metadata.nonDeferredFkOrder ?? 0) - (b.metadata.nonDeferredFkOrder ?? 0),\n  );\n  for (const todo of sorted) {\n    addInserts(ops, todo, fixups);\n    addUpdates(ops, todo);\n    addDeletes(ops, todo);\n  }\n  if (fixups.length > 0) translateFixupsIntoUpdates(ops, fixups);\n  return ops;\n}\n\nfunction addInserts(ops: Ops, todo: Todo, fixups: InsertFixup[]): void {\n  if (todo.inserts.length > 0) {\n    // If we have subtypes, this todo.metadata will always be the base type\n    const meta = todo.metadata;\n    if (meta.subTypes.length > 0) {\n      if (meta.inheritanceType === \"cti\") {\n        // Insert into each of the CTI tables\n        for (const [meta, group] of groupEntitiesByTable(todo.inserts)) {\n          ops.inserts.push(newInsertOp(meta, group, fixups));\n        }\n      } else if (meta.inheritanceType === \"sti\") {\n        // One INSERT per subtype, so each statement's column list spans exactly what that subtype can\n        // set. A single statement across subtypes has to bind NULL for the other subtypes' columns,\n        // which defeats their database defaults, and outright fails for notNull ones.\n        for (const group of groupBy(todo.inserts, (e) => getMetadata(e)).values()) {\n          ops.inserts.push(newStiInsertOp(meta, group, fixups));\n        }\n      } else {\n        throw new Error(`Found ${meta.tableName} subTypes without a known inheritanceType ${meta.inheritanceType}`);\n      }\n    } else {\n      ops.inserts.push(newInsertOp(meta, todo.inserts, fixups));\n    }\n  }\n}\n\nfunction newInsertOp(meta: EntityMetadata, entities: Entity[], fixups: InsertFixup[]): InsertOp {\n  // Purposefully use `meta.fields` instead of `allFields` b/c each CTI table has its own `InsertOp`\n  const columns = Object.values(meta.fields)\n    .filter(hasSerde)\n    .flatMap((f) => f.serde.columns);\n  const columnValues = collectBindings(entities, meta.tableName, columns, fixups);\n  return { tableName: meta.tableName, columns, columnValues };\n}\n\nfunction newStiInsertOp(root: EntityMetadata, entities: Entity[], fixups: InsertFixup[]): InsertOp {\n  // `allFields` is the base's fields plus this subtype's own, i.e. everything this subtype can write.\n  // Anything it can't write is left out of the statement entirely, so the database applies its default.\n  const fields: Field[] = Object.values(getMetadata(entities[0]).allFields);\n  const columns = fields.filter(hasSerde).flatMap((f) => f.serde.columns);\n  const columnValues = collectBindings(entities, root.tableName, columns, fixups);\n  return { tableName: root.tableName, columns, columnValues };\n}\n\nfunction addUpdates(ops: Ops, todo: Todo): void {\n  if (todo.updates.length > 0) {\n    const meta = todo.metadata;\n    if (meta.subTypes.length > 0) {\n      if (meta.inheritanceType === \"cti\") {\n        for (const [meta, group] of groupEntitiesByTable(todo.updates)) {\n          const op = newUpdateOp(meta, group);\n          if (op) ops.updates.push(op);\n          addLazyUpdates(ops, meta, group);\n        }\n      } else if (meta.inheritanceType === \"sti\") {\n        const op = newUpdateOp(meta, todo.updates);\n        if (op) ops.updates.push(op);\n        addLazyUpdates(ops, meta, todo.updates);\n      } else {\n        throw new Error(`Found ${meta.tableName} subTypes without a known inheritanceType ${meta.inheritanceType}`);\n      }\n    } else {\n      const op = newUpdateOp(meta, todo.updates);\n      if (op) ops.updates.push(op);\n      addLazyUpdates(ops, meta, todo.updates);\n    }\n  }\n}\n\n/**\n * Writes changed `lazy` columns via a targeted `UPDATE table SET lazy_col = ... WHERE id in (...)`.\n *\n * Lazy columns are excluded from the main batch UPDATE (which spans the batch's union of changed fields),\n * so that entities in the batch that never loaded a lazy column keep their existing db value instead of\n * being overwritten with null. Here we write each lazy column only for the entities that actually changed it.\n */\nfunction addLazyUpdates(ops: Ops, meta: EntityMetadata, entities: Entity[]): void {\n  const idColumn = meta.fields[\"id\"].serde!.columns[0];\n  for (const fieldName of meta.lazyFieldNames!) {\n    const field = meta.fields[fieldName];\n    if (!hasSerde(field)) continue;\n    const changed = entities.filter((e) => fieldName in getInstanceData(e).changedData);\n    if (changed.length === 0) continue;\n    const columns: BindingColumn[] = [idColumn, ...field.serde.columns];\n    const columnValues = collectBindings(changed, meta.tableName, columns, undefined);\n    ops.updates.push({ tableName: meta.tableName, columns, columnValues, updatedAt: undefined });\n  }\n}\n\nfunction newUpdateOp(meta: EntityMetadata, entities: Entity[]): UpdateOp | undefined {\n  // We only include changed fields in our `UPDATE`--maybe we could change this\n  // to always use the same fields, to take advantage of Prepared Statements.\n  const changedFields = new Set<string>();\n  for (const entity of entities) {\n    for (const fieldName in getInstanceData(entity).changedData) changedFields.add(fieldName);\n  }\n  // Sometimes with derived fields, an instance will be marked as an update, but if the derived field hasn't\n  // actually changed, it'll be a noop, so just short-circuit if it looks like that happened. Unless touched.\n  if (changedFields.size === 0 && !entities.some((e) => getInstanceData(e).isTouched)) {\n    return undefined;\n  }\n\n  // We may have loaded a1 and a2, and changed a1.firstName, and a2.lastName, but either one\n  // might be missing the other's changed fields in it's lazy-initialized data field...\n  // (Use `?` because subtypes won't have the updatedAt, and it will be handled by the base type\n  // `newUpdateUp`--except STI where we're doing it all in one go, probably needs checked here.)\n  const updatedAt = meta.timestampFields?.updatedAt;\n  changedFields.add(\"id\");\n  if (updatedAt) changedFields.add(updatedAt);\n  // `lazy` columns are deliberately excluded from the batch UPDATE and written by `addLazyUpdates`; an\n  // entity that never loaded a lazy column isn't in `row`, so forcing `getField` here would clobber it to null.\n  const lazyFieldNames = meta.lazyFieldNames!;\n  for (const entity of entities) {\n    const { data } = getInstanceData(entity);\n    for (const key of changedFields) {\n      // Check isChangeableField because we might be updating the base `publishers` table\n      // and `originalData` might have fields from a subclass `large_publishers` table.\n      if (!(key in data) && isChangeableField(entity, key) && !lazyFieldNames.has(key)) {\n        getField(entity, key);\n      }\n    }\n  }\n\n  const columns: Array<BindingColumn> = (\n    meta.inheritanceType === \"sti\"\n      ? // Hack this one handling of STI into here...\n        getBaseSelfAndSubMetas(meta).flatMap((meta) =>\n          meta.stiDiscriminatorField\n            ? Object.values(meta.fields)\n            : Object.values(meta.fields).filter((f) => f.fieldName !== \"id\"),\n        )\n      : Object.values(meta.fields)\n  )\n    .filter((f) => changedFields.has(f.fieldName))\n    .filter((f) => !lazyFieldNames.has(f.fieldName))\n    .filter(hasSerde)\n    .flatMap((f) => f.serde.columns);\n\n  // If we're using class table inheritance, base/child tables may not have any columns to update\n  if (columns.length === 1) {\n    return undefined;\n  }\n\n  // We already have the bumped updated_at column, but also include the original updated_at for the data CTE\n  if (updatedAt) {\n    const serde = meta.fields[updatedAt].serde as TimestampSerde<unknown>;\n    columns.push({\n      columnName: \"__original_updated_at\",\n      dbType: \"timestamptz\",\n      dbValue: (_, entity) => serde.dbValue(getInstanceData(entity).originalData),\n    });\n  }\n\n  const columnValues = collectBindings(entities, meta.tableName, columns, []);\n  const updatedAtColumn = updatedAt ? (meta.fields[updatedAt] as PrimitiveField).serde.columns[0] : undefined;\n  return { tableName: meta.tableName, columns, updatedAt: updatedAtColumn?.columnName, columnValues };\n}\n\nfunction addDeletes(ops: Ops, todo: Todo): void {\n  if (todo.deletes.length > 0) {\n    const meta = todo.metadata;\n    const ids = todo.deletes.map((e) => keyToNumber(meta, e.idTagged!).toString());\n    if (meta.subTypes.length > 0) {\n      getBaseSelfAndSubMetas(meta).forEach((meta) => {\n        ops.deletes.push({ tableName: meta.tableName, ids });\n      });\n    } else {\n      ops.deletes.push({ tableName: meta.tableName, ids });\n    }\n  }\n}\n\nfunction groupEntitiesByTable(entities: Entity[]): Array<[EntityMetadata, Entity[]]> {\n  const entitiesByType: Map<EntityMetadata, Entity[]> = new Map();\n  for (const e of entities) {\n    for (const m of getBaseAndSelfMetas(getMetadata(e))) {\n      let list = entitiesByType.get(m);\n      if (!list) {\n        list = [];\n        entitiesByType.set(m, list);\n      }\n      list.push(e);\n    }\n  }\n  return [...entitiesByType.entries()];\n}\n\ntype BindingColumn = OpColumn & Pick<FieldColumn, \"dbValue\">;\ntype EntityWithData = Entity & { __data: { data: Record<string, unknown> } };\n\n/**\n * Builds a *columnar* array of bindings for the given `entities` and `columns`.\n *\n * We use a columnar approach, instead of `rows[]`, to best match the unnest-based\n * column operations in our `batchInsert` / `batchUpdate` SQL statements.\n */\nfunction collectBindings(\n  entities: Entity[],\n  tableName: string,\n  columns: BindingColumn[],\n  fixups: InsertFixup[] | undefined,\n): any[][] {\n  const entityCount = entities.length;\n  const bindings: any[][] = new Array(columns.length);\n  const entitiesWithData = entities as EntityWithData[];\n  // Cache data separately; this benchmarks faster than `entities[i].__data.data` in the inner loop.\n  const entityData = new Array(entityCount);\n  for (let i = 0; i < entityCount; i++) entityData[i] = entitiesWithData[i].__data.data;\n  for (let columnIndex = 0; columnIndex < columns.length; columnIndex++) {\n    const column = columns[columnIndex];\n    const columnValues: any[] = new Array(entityCount);\n    for (let entityIndex = 0; entityIndex < entityCount; entityIndex++) {\n      columnValues[entityIndex] =\n        column.dbValue(entityData[entityIndex], entities[entityIndex], tableName, fixups) ?? null;\n    }\n    bindings[columnIndex] = columnValues;\n  }\n  return bindings;\n}\n/**\n * Given `fixups` that indicate where we inserted `NULL` into non-deferred FKs, create `UPDATE`s\n * that insert the value now that the FK check will succeed.\n */\nfunction translateFixupsIntoUpdates(ops: Ops, fixups: InsertFixup[]): void {\n  // Create a single `UPDATE` for the N fixups we might have for each table/column combination\n  groupBy(fixups, (f) => `${f.tableName}.${f.column.columnName}`).forEach((fixups) => {\n    const { tableName, entity, column } = fixups[0];\n    ops.updates.push({\n      tableName,\n      columns: [getMetadata(entity).fields[\"id\"].serde!.columns[0], column],\n      columnValues: [\n        // Make 1 column of ids, and 1 column of values\n        fixups.map((fixup) => fixup.entity.id),\n        fixups.map((fixup) => fixup.value),\n      ],\n      updatedAt: undefined,\n    });\n  });\n}\n"],"mappings":"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"}

package/build/drivers/EntityWriter.d.cts

@@ -0,0 +1,66 @@
+import { Todo } from "../flush/Todo.cjs";
+import { Entity } from "../Entity.cjs";
+//#region src/drivers/EntityWriter.d.ts
+/** A simplified view of columns, with only the keys necessary to create SQL statements. */
+type OpColumn = {
+  columnName: string;
+  dbType: string;
+  isNullableArray?: boolean;
+};
+type InsertOp = {
+  tableName: string;
+  columns: OpColumn[];
+  columnValues: any[][];
+};
+/**
+ * A logical `update` operation.
+ *
+ * If we're using op locks, `columns` will include both the new `updatedAt` value (as bumped
+ * by the `EntityManager` on mutate), as well as an extra/last "original updated at" column
+ * (with respective pre-update values in the `rows` data), for including in the conditional
+ * update clause.
+ */
+type UpdateOp = {
+  tableName: string;
+  columns: OpColumn[];
+  columnValues: any[][];
+  updatedAt: string | undefined;
+};
+type DeleteOp = {
+  tableName: string;
+  ids: any[];
+};
+type Ops = {
+  inserts: InsertOp[];
+  updates: UpdateOp[];
+  deletes: DeleteOp[];
+};
+/**
+ * In schemas with entity FK cycles, we may insert a dummy/null value, and later fix it up
+ * before the transaction commits.
+ *
+ * I.e. `INSERT author.favorite_book_id` as `NULL` and then later do an `UPDATE author
+ * SET favorite_book_id = 1` after the book has been inserted/we have the id.
+ */
+type InsertFixup = {
+  entity: Entity;
+  tableName: string;
+  column: OpColumn;
+  value: any;
+};
+/**
+ * Builds AST-ish `Ops` for the inserts/updates/deletes in `todos`.
+ *
+ * This helps decouple the database-specific driver/library from the knowledge
+ * of turning entities into table operations, i.e. so they can be unaware of
+ * complexities like field -> column mapping, oplocks, and class table inheritance.
+ *
+ * We still assume Postgres b/c we assume all ids have been pre-assigned for INSERTs,
+ * and don't do any topological sorting of cross-row FK dependencies.
+ *
+ * But this should let us experiment with knex vs. raw client/etc.
+ */
+declare function generateOps(todos: Record<string, Todo>): Ops;
+//#endregion
+export { DeleteOp, InsertFixup, InsertOp, OpColumn, UpdateOp, generateOps };
+//# sourceMappingURL=EntityWriter.d.cts.map

package/build/drivers/EntityWriter.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityWriter.d.cts","names":[],"sources":["../../src/drivers/EntityWriter.ts"],"mappings":";;;;KAiBY;EAAa;EAAoB;EAAgB;;KACjD;EAAa;EAAmB,SAAS;EAAY;;;;;;;;;;KASrD;EACV;EACA,SAAS;EACT;EACA;;KAEU;EAAa;EAAmB;;KAEvC;EAAQ,SAAS;EAAY,SAAS;EAAY,SAAS;;;;;;;;;KASpD;EACV,QAAQ;EACR;EACA,QAAQ;EACR;;;;;;;;;;;;;;iBAec,YAAY,OAAO,eAAe,QAAQ"}

package/build/drivers/EntityWriter.d.mts

@@ -0,0 +1,66 @@
+import { Todo } from "../flush/Todo.mjs";
+import { Entity } from "../Entity.mjs";
+//#region src/drivers/EntityWriter.d.ts
+/** A simplified view of columns, with only the keys necessary to create SQL statements. */
+type OpColumn = {
+  columnName: string;
+  dbType: string;
+  isNullableArray?: boolean;
+};
+type InsertOp = {
+  tableName: string;
+  columns: OpColumn[];
+  columnValues: any[][];
+};
+/**
+ * A logical `update` operation.
+ *
+ * If we're using op locks, `columns` will include both the new `updatedAt` value (as bumped
+ * by the `EntityManager` on mutate), as well as an extra/last "original updated at" column
+ * (with respective pre-update values in the `rows` data), for including in the conditional
+ * update clause.
+ */
+type UpdateOp = {
+  tableName: string;
+  columns: OpColumn[];
+  columnValues: any[][];
+  updatedAt: string | undefined;
+};
+type DeleteOp = {
+  tableName: string;
+  ids: any[];
+};
+type Ops = {
+  inserts: InsertOp[];
+  updates: UpdateOp[];
+  deletes: DeleteOp[];
+};
+/**
+ * In schemas with entity FK cycles, we may insert a dummy/null value, and later fix it up
+ * before the transaction commits.
+ *
+ * I.e. `INSERT author.favorite_book_id` as `NULL` and then later do an `UPDATE author
+ * SET favorite_book_id = 1` after the book has been inserted/we have the id.
+ */
+type InsertFixup = {
+  entity: Entity;
+  tableName: string;
+  column: OpColumn;
+  value: any;
+};
+/**
+ * Builds AST-ish `Ops` for the inserts/updates/deletes in `todos`.
+ *
+ * This helps decouple the database-specific driver/library from the knowledge
+ * of turning entities into table operations, i.e. so they can be unaware of
+ * complexities like field -> column mapping, oplocks, and class table inheritance.
+ *
+ * We still assume Postgres b/c we assume all ids have been pre-assigned for INSERTs,
+ * and don't do any topological sorting of cross-row FK dependencies.
+ *
+ * But this should let us experiment with knex vs. raw client/etc.
+ */
+declare function generateOps(todos: Record<string, Todo>): Ops;
+//#endregion
+export { DeleteOp, InsertFixup, InsertOp, OpColumn, UpdateOp, generateOps };
+//# sourceMappingURL=EntityWriter.d.mts.map

package/build/drivers/EntityWriter.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"EntityWriter.d.mts","names":[],"sources":["../../src/drivers/EntityWriter.ts"],"mappings":";;;;KAiBY;EAAa;EAAoB;EAAgB;;KACjD;EAAa;EAAmB,SAAS;EAAY;;;;;;;;;;KASrD;EACV;EACA,SAAS;EACT;EACA;;KAEU;EAAa;EAAmB;;KAEvC;EAAQ,SAAS;EAAY,SAAS;EAAY,SAAS;;;;;;;;;KASpD;EACV,QAAQ;EACR;EACA,QAAQ;EACR;;;;;;;;;;;;;;iBAec,YAAY,OAAO,eAAe,QAAQ"}