@c9up/atlas 0.3.6 → 0.3.8

package/src/BaseRepository.ts

@@ -198,6 +198,30 @@ const POSTGRES_CAST_TYPES = new Set([
 	"float",
 ]);
 
+/**
+ * Parse a JSON column's text, or hand back the text unchanged.
+ *
+ * Unparseable text is a row the column's type says cannot exist — on SQLite it
+ * can, because the column is TEXT there and nothing enforces the shape. Failing
+ * the hydration would make the whole row unreadable, including the columns that
+ * are fine, so the raw string is returned: visible at the use site, and nothing
+ * is lost or rewritten.
+ */
+function parseJsonColumn(text: string): unknown {
+	try {
+		return JSON.parse(text);
+	} catch {
+		return text;
+	}
+}
+
+/** Whether a declared `@Column({ type })` is a JSON column. */
+function isJsonType(type: string | undefined): boolean {
+	if (type === undefined) return false;
+	const normalized = type.trim().toLowerCase();
+	return normalized === "json" || normalized === "jsonb";
+}
+
 /**
  * Snake column → logical type for params needing a Postgres `$N::<type>` cast.
  * sqlx binds JS strings as `text`; Postgres won't implicitly coerce that to
@@ -266,6 +290,14 @@ export class BaseRepository<T extends BaseEntity> {
 	#columnMap: Map<string, string>; // property/db name → resolved db column (cached)
 	#columnByDbName: Map<string, string>; // resolved db column → property (for hydrate)
 	#dateColumns: Record<string, DateColumnConfig>;
+	/**
+	 * Properties declared `@Column({ type: 'json' })` / `'jsonb'`.
+	 *
+	 * They get the same treatment date columns get: serialised on the way down,
+	 * parsed on the way back, without the application writing a `prepare` /
+	 * `consume` pair for a conversion the declared type already states.
+	 */
+	#jsonColumns: Set<string>;
 	/** Snake column → logical type for params needing a Postgres `::cast`. */
 	#castTypes: Record<string, string>;
 	/**
@@ -343,6 +375,11 @@ export class BaseRepository<T extends BaseEntity> {
 		this.#columns = columnsMeta.map((c) => c.propertyKey);
 		this.#softDeletes = hasSoftDeletes(entityClass);
 		this.#dateColumns = getDateColumnConfig(entityClass);
+		this.#jsonColumns = new Set(
+			columnsMeta
+				.filter((col) => isJsonType(col.type))
+				.map((col) => col.propertyKey),
+		);
 
 		// Lift per-column `prepare` / `consume` callbacks directly from metadata.
 		// No global registry, no late-registration concern: callbacks are baked
@@ -1419,6 +1456,18 @@ export class BaseRepository<T extends BaseEntity> {
 		// Branch order mirrors Lucid's `prepareDateColumn` (strings pass through,
 		// `DateTime` is formatted, anything else throws naming the column) — see
 		// `#prepareDateString` for the one named deviation.
+		// A JSON column takes the value as JSON text — objects and arrays alike.
+		// The binder underneath is typed strictly, so nothing downstream guesses
+		// what a JS value meant, and doing the encoding here is what makes the
+		// three dialects behave identically. A string is passed through: it is
+		// already JSON text, or a scalar the column accepts as-is.
+		if (
+			this.#jsonColumns.has(propertyKey) &&
+			typeof value === "object" &&
+			value !== null
+		) {
+			return JSON.stringify(value);
+		}
 		const dateColumn = this.#dateColumns[propertyKey];
 		if (dateColumn && value != null) {
 			// `@column.date()` persists the date alone, like Lucid's
@@ -1500,6 +1549,14 @@ export class BaseRepository<T extends BaseEntity> {
 		if (this.#dateColumns[propertyKey] && value != null) {
 			return dateTimeAtlasAdapter.consume(value);
 		}
+		// A JSON column hydrates to the value it holds, not to its text. The
+		// native Postgres pool already decodes `json`/`jsonb` to a real value;
+		// this is what makes MySQL and SQLite — where the column is TEXT — agree
+		// with it, instead of handing the application a string on two dialects
+		// out of three.
+		if (this.#jsonColumns.has(propertyKey) && typeof value === "string") {
+			return parseJsonColumn(value);
+		}
 		return value;
 	}
 
@@ -1538,13 +1595,25 @@ export class BaseRepository<T extends BaseEntity> {
 			const now = DateTime.now();
 			await this.#runUpdate(
 				[[this.#dbColumn("deletedAt"), now.toISO()]],
-				[{ column: this.#primaryKey, operator: "=", value: pk, type: "and" }],
+				[
+					{
+						column: this.#dbColumn(this.#primaryKey),
+						operator: "=",
+						value: pk,
+						type: "and",
+					},
+				],
 			);
 			// In-memory value is a Chronos DateTime, matching how date columns hydrate.
 			entity.setProp("deletedAt", now);
 		} else {
 			await this.#runDelete([
-				{ column: this.#primaryKey, operator: "=", value: pk, type: "and" },
+				{
+					column: this.#dbColumn(this.#primaryKey),
+					operator: "=",
+					value: pk,
+					type: "and",
+				},
 			]);
 		}
 		entity.markAsDeleted();
@@ -1562,7 +1631,7 @@ export class BaseRepository<T extends BaseEntity> {
 		await fireHooks(this.#entityClass, "beforeDelete", entity);
 		await this.#runDelete([
 			{
-				column: this.#primaryKey,
+				column: this.#dbColumn(this.#primaryKey),
 				operator: "=",
 				value: entity[this.#primaryKey],
 				type: "and",
@@ -1579,7 +1648,7 @@ export class BaseRepository<T extends BaseEntity> {
 			[[this.#dbColumn("deletedAt"), null]],
 			[
 				{
-					column: this.#primaryKey,
+					column: this.#dbColumn(this.#primaryKey),
 					operator: "=",
 					value: entity[this.#primaryKey],
 					type: "and",
@@ -1597,7 +1666,12 @@ export class BaseRepository<T extends BaseEntity> {
 	): Promise<void> {
 		const set = this.#buildSetPairs(data);
 		await this.#runUpdate(set, [
-			{ column: this.#primaryKey, operator: "=", value: id, type: "and" },
+			{
+				column: this.#dbColumn(this.#primaryKey),
+				operator: "=",
+				value: id,
+				type: "and",
+			},
 		]);
 	}
 
@@ -1646,7 +1720,12 @@ export class BaseRepository<T extends BaseEntity> {
 	): Promise<void> {
 		const set = this.#buildIncrementPairs(columnOrMap, amount, "increment");
 		await this.#runUpdate(set, [
-			{ column: this.#primaryKey, operator: "=", value: id, type: "and" },
+			{
+				column: this.#dbColumn(this.#primaryKey),
+				operator: "=",
+				value: id,
+				type: "and",
+			},
 		]);
 	}
 
@@ -1667,7 +1746,12 @@ export class BaseRepository<T extends BaseEntity> {
 	): Promise<void> {
 		const set = this.#buildIncrementPairs(columnOrMap, amount, "decrement");
 		await this.#runUpdate(set, [
-			{ column: this.#primaryKey, operator: "=", value: id, type: "and" },
+			{
+				column: this.#dbColumn(this.#primaryKey),
+				operator: "=",
+				value: id,
+				type: "and",
+			},
 		]);
 	}
 
@@ -1919,7 +2003,12 @@ export class BaseRepository<T extends BaseEntity> {
 		}
 
 		await this.#runUpdate(setPairs, [
-			{ column: this.#primaryKey, operator: "=", value: pk, type: "and" },
+			{
+				column: this.#dbColumn(this.#primaryKey),
+				operator: "=",
+				value: pk,
+				type: "and",
+			},
 		]);
 		// Re-snapshot after a successful UPDATE.
 		entity.markAsPersisted();

package/src/adapters/NapiDbAdapter.ts

@@ -45,6 +45,11 @@ function napiReplacer(_key: string, value: unknown): unknown {
  *
  * Only the TOP level is checked: a nested array is a JSON value inside an
  * object being bound to a `json`/`jsonb` column, which is legitimate.
+ *
+ * A column declared `@Column({ type: 'json' })` never reaches here as an array:
+ * the repository serialises it on the way down, the way it lowers a date
+ * column. This fires for the list that was meant to be an `IN`, and for a raw
+ * query with no entity behind it to say what the column holds.
  */
 function assertNoArrayParams(params: readonly unknown[] | undefined): void {
 	if (!params) return;
@@ -52,8 +57,11 @@ function assertNoArrayParams(params: readonly unknown[] | undefined): void {
 		if (!Array.isArray(value)) continue;
 		throw new Error(
 			`[E_ARRAY_PARAM] Parameter $${index + 1} is an array, which cannot be bound as a single value. ` +
-				"Expand it into one placeholder per element — `whereIn(column, values)` does this, " +
-				"and so does building the placeholders yourself: `IN (${values.map((_, i) => '$' + (i + 1)).join(', ')})`. " +
+				"For a list of values, expand it into one placeholder per element — `whereIn(column, values)` " +
+				"does this, and so does building the placeholders yourself: " +
+				`\`IN (\${values.map((_, i) => '$' + (i + 1)).join(', ')})\`. ` +
+				"For a JSON column, declare it — `@Column({ type: 'jsonb' })` — and the array is serialised " +
+				"and parsed for you; on a raw query with no entity behind it, pass `JSON.stringify(value)`. " +
 				"Binding the array itself sends Postgres text where it expects an array, and it reports " +
 				"a nonsensical dimension count rather than a type error.",
 		);
@@ -303,9 +311,10 @@ export async function createNapiConnection(
 				sql: string,
 				params: unknown[] = [],
 			): Promise<{ rowsAffected: number; lastInsertId?: number }> {
+				assertNoArrayParams(params);
 				const json = await native.execute(
 					sql,
-					(assertNoArrayParams(params), JSON.stringify(params, napiReplacer)),
+					JSON.stringify(params, napiReplacer),
 				);
 				const r = JSON.parse(json);
 				return {
@@ -318,9 +327,10 @@ export async function createNapiConnection(
 				sql: string,
 				params: unknown[] = [],
 			): Promise<T[]> {
+				assertNoArrayParams(params);
 				const json = await native.query(
 					sql,
-					(assertNoArrayParams(params), JSON.stringify(params, napiReplacer)),
+					JSON.stringify(params, napiReplacer),
 				);
 				return JSON.parse(json, napiReviver) as T[];
 			},
@@ -446,8 +456,8 @@ export async function createNapiConnection(
 			meta?: QueryMeta,
 		): Promise<T[]> {
 			return observed(sql, params, meta, async () => {
-				const paramsJson =
-					(assertNoArrayParams(params), JSON.stringify(params, napiReplacer));
+				assertNoArrayParams(params);
+				const paramsJson = JSON.stringify(params, napiReplacer);
 				const json =
 					meta?.serverTimeoutMs != null
 						? await db.queryTimed(sql, paramsJson, meta.serverTimeoutMs)
@@ -462,8 +472,8 @@ export async function createNapiConnection(
 			meta?: QueryMeta,
 		): Promise<{ rowsAffected: number; lastInsertId?: number }> {
 			return observed(sql, params, meta, async () => {
-				const paramsJson =
-					(assertNoArrayParams(params), JSON.stringify(params, napiReplacer));
+				assertNoArrayParams(params);
+				const paramsJson = JSON.stringify(params, napiReplacer);
 				const json =
 					meta?.serverTimeoutMs != null
 						? await db.executeTimed(sql, paramsJson, meta.serverTimeoutMs)

package/src/decorators/entity.ts

@@ -214,7 +214,7 @@ export function Entity(tableName: string): ClassDecorator {
 }
 
 /** @Column() — marks a property as a database column. */
-export function Column(options?: ColumnOptions): PropertyDecorator {
+function ColumnBase(options?: ColumnOptions): PropertyDecorator {
 	return (target, propertyKey) => {
 		const columns: ColumnMetadata[] =
 			Reflect.getOwnMetadata(COLUMNS_KEY, target.constructor) ?? [];
@@ -362,23 +362,64 @@ function columnDateTime(options?: DateTimeColumnOptions): PropertyDecorator {
 	};
 }
 
-/** Namespace access so users write `@column.date()` / `@column.dateTime()`. */
-const columnWithSubs = Column as typeof Column & {
-	date: typeof columnDate;
-	dateTime: typeof columnDateTime;
-};
-columnWithSubs.date = columnDate;
-columnWithSubs.dateTime = columnDateTime;
+/** Options for `@Column.json()`. */
+export interface JsonColumnOptions extends ColumnOptions {
+	/**
+	 * The SQL type the column is declared with. `jsonb` by default — the binary
+	 * form, which is what a Postgres schema almost always wants. Pass `'json'`
+	 * for the textual one.
+	 */
+	type?: "json" | "jsonb";
+}
 
 /**
- * `Column` exposed with its sub-decorators (`Column.date()`, `Column.dateTime()`).
- * Alias exports so TS users can `import { column } from '@c9up/atlas'` for a
- * Lucid-style lowercase naming when they prefer.
+ * `@Column.json()` — a column holding a JSON document.
+ *
+ * The property keeps its JavaScript shape on both sides: assign an object or an
+ * array, read an object or an array back. atlas serialises the value when it
+ * writes the row and parses it when it reads one, so nothing in the application
+ * converts by hand, and every dialect behaves the same — Postgres decodes JSON
+ * itself, while SQLite and MySQL store text.
+ *
+ *   @Column.json() declare metadata: Record<string, unknown> | null
+ *   @Column.json({ type: 'json' }) declare tags: string[] | null
+ *
+ * A `prepare` or `consume` given here still wins: the column is yours to
+ * encode differently when the document needs it.
+ *
+ * Declaring `@Column({ type: 'jsonb' })` does the same thing — the type is what
+ * atlas reads — but this says it in one place and cannot be mistyped.
  */
-export const column = Column as typeof Column & {
+function columnJson(options?: JsonColumnOptions): PropertyDecorator {
+	return (target, propertyKey) => {
+		Column({ ...options, type: options?.type ?? "jsonb" })(target, propertyKey);
+	};
+}
+
+/**
+ * `@Column()` with its sub-decorators attached: `Column.date()`,
+ * `Column.dateTime()`, `Column.json()`.
+ *
+ * The type carries them too — attaching them to the plain function left
+ * `Column.date` working at runtime but unknown to TypeScript, so only the
+ * lowercase alias type-checked.
+ */
+const ColumnWithSubs = ColumnBase as typeof ColumnBase & {
 	date: typeof columnDate;
 	dateTime: typeof columnDateTime;
+	json: typeof columnJson;
 };
+ColumnWithSubs.date = columnDate;
+ColumnWithSubs.dateTime = columnDateTime;
+ColumnWithSubs.json = columnJson;
+
+export const Column = ColumnWithSubs;
+
+/**
+ * Also exported lowercase, so `import { column } from '@c9up/atlas'` reads the
+ * way a schema definition usually does. The same decorator, either spelling.
+ */
+export const column = ColumnWithSubs;
 
 /** Read the date-column configuration map for an entity class (walks prototype chain). */
 export function getDateColumnConfig(

package/src/index.ts

@@ -72,6 +72,7 @@ export type {
 	DateColumnConfig,
 	DateTimeColumnOptions,
 	EntityMetadata,
+	JsonColumnOptions,
 	ManyToManyOptions,
 	RelationMetadata,
 } from "./decorators/entity.js";

package/src/schema/MigrationRunner.ts

@@ -93,6 +93,7 @@ export interface DatabaseAdapter {
 	execute(
 		sql: string,
 		params?: unknown[],
+		// biome-ignore lint/suspicious/noConfusingVoidType: `void` is the point — an implementation that returns nothing must satisfy this, and `undefined` rejects a `Promise<void>`.
 	): Promise<void | { rowsAffected: number }>;
 	/** Query rows with optional parameterized values. */
 	query<T>(sql: string, params?: unknown[]): Promise<T[]>;