@ultimat3/entity 0.0.1 → 1.0.0

package/src/columns.js

@@ -0,0 +1,136 @@
+// The blessed column builders. There is exactly one way to store an id, an instant, money, a
+// locale and a time zone — the alternatives (float money, naive timestamps, a single implied
+// currency) are the bugs this file exists to make unreachable.
+import { uuid as uuidV7 } from '@ultimat3/core';
+import { BARE, column, GENERATED_UUID, makeColumn, makeTimestamp } from './column';
+import { invariantViolated } from './errors';
+const reject = (rule, detail) => {
+    throw invariantViolated('column', rule, detail);
+};
+/** uuid v7: time-ordered, so a primary key index stays append-friendly. */
+export const newId = () => uuidV7();
+const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+const parseUuid = (value) => typeof value === 'string' && UUID.test(value)
+    ? value
+    : reject('format', `expected a uuid, got ${String(value)}`);
+export const uuid = () => ({
+    ...makeColumn({ ...BARE, kind: 'uuid' }, parseUuid, false),
+    // Narrower than the generic chain: a uuid key is generated when omitted, so it is the one
+    // primary key an insert may leave out.
+    primaryKey: () => makeColumn({ ...BARE, kind: 'uuid', primaryKey: true, default: GENERATED_UUID }, parseUuid, true),
+});
+export const text = (options = {}) => column('text', (value) => typeof value === 'string' ? value : reject('type', `expected a string, got ${typeof value}`), options.max === undefined
+    ? {}
+    : { length: options.max, check: (name) => `char_length(${name}) <= ${options.max}` });
+export const integer = () => column('integer', (value) => typeof value === 'number' && Number.isSafeInteger(value)
+    ? value
+    : reject('type', `expected a safe integer, got ${String(value)}`));
+export const boolean = () => column('boolean', (value) => typeof value === 'boolean' ? value : reject('type', `expected a boolean, got ${typeof value}`));
+const parseInstant = (value) => {
+    if (value instanceof Date && !Number.isNaN(value.getTime()))
+        return value;
+    if (typeof value === 'string' || typeof value === 'number') {
+        const parsed = new Date(value);
+        if (!Number.isNaN(parsed.getTime()))
+            return parsed;
+    }
+    return reject('format', `expected a UTC instant, got ${String(value)}`);
+};
+/** Always `timestamptz`. UTC storage is not a per-table decision. */
+export const timestamp = () => makeTimestamp({ ...BARE, kind: 'timestamptz' }, parseInstant, false);
+const quote = (value) => `'${value.replaceAll("'", "''")}'`;
+const oneOf = (values) => (name) => `${name} in (${values.map(quote).join(', ')})`;
+/**
+ * A closed set of strings, emitted as a CHECK rather than a Postgres `ENUM` type: adding a
+ * variant is then a one-line migration instead of `ALTER TYPE`, which cannot run inside a
+ * transaction on older servers.
+ */
+export const enumerated = (values) => {
+    const allowed = new Set(values);
+    return column('text', (value) => typeof value === 'string' && allowed.has(value)
+        ? value
+        : reject('enum', `expected one of ${values.join(' | ')}, got ${String(value)}`), { values, check: oneOf(values) });
+};
+/**
+ * An absolute http(s) URL, validated on write rather than on render: a bad URL stored once is
+ * served to every reader, and `<img src>` fails silently in the browser.
+ */
+export const url = () => column('text', (value) => {
+    if (typeof value === 'string') {
+        try {
+            const parsed = new URL(value);
+            if (parsed.protocol === 'http:' || parsed.protocol === 'https:')
+                return value;
+        }
+        catch {
+            // fall through to the shared rejection so the error names the rule
+        }
+    }
+    return reject('format', `expected an absolute http(s) URL, got ${String(value)}`);
+}, { check: (name) => `${name} ~ '^https?://'` });
+const isIanaZone = (value) => {
+    try {
+        new Intl.DateTimeFormat('en', { timeZone: value }).format(0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * IANA identifiers, checked against `Intl` when the column is declared — a typo or a UTC offset
+ * is a startup error rather than a row nobody can format. An offset is wrong twice a year.
+ */
+export const tz = (zones) => {
+    for (const zone of zones) {
+        if (!isIanaZone(zone))
+            reject('iana-tz', `${zone} is not an IANA time zone`);
+    }
+    const allowed = new Set(zones);
+    return column('text', (value) => typeof value === 'string' && allowed.has(value)
+        ? value
+        : reject('iana-tz', `expected one of ${zones.join(' | ')}, got ${String(value)}`), { values: zones, check: oneOf(zones) });
+};
+const BCP47 = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+export const locale = (locales) => {
+    for (const tag of locales) {
+        if (!BCP47.test(tag))
+            reject('bcp-47', `${tag} is not a BCP-47 language tag`);
+    }
+    const allowed = new Set(locales);
+    return column('text', (value) => typeof value === 'string' && allowed.has(value)
+        ? value
+        : reject('bcp-47', `expected one of ${locales.join(' | ')}, got ${String(value)}`), { values: locales, check: oneOf(locales) });
+};
+const parseMinor = (value) => {
+    if (typeof value === 'bigint')
+        return value;
+    if (typeof value === 'number') {
+        if (!Number.isInteger(value)) {
+            return reject('money-minor-units', `got the float ${value}; money is integer minor units — 12.34 EUR is 1234n, not 12.34`);
+        }
+        return BigInt(value);
+    }
+    if (typeof value === 'string' && /^-?\d+$/.test(value))
+        return BigInt(value);
+    return reject('money-minor-units', `expected integer minor units, got ${String(value)}`);
+};
+const parseCurrency = (value) => typeof value === 'string' && /^[A-Z]{3}$/.test(value)
+    ? value
+    : reject('iso-4217', `expected a 3-letter ISO-4217 code, got ${String(value)}`);
+const parseMoney = (value) => {
+    if (typeof value !== 'object' || value === null) {
+        return reject('money', `expected { minor, currency }, got ${String(value)}`);
+    }
+    const input = value;
+    return { minor: parseMinor(input.minor), currency: parseCurrency(input.currency) };
+};
+/**
+ * One property, two physical columns: `<name>_minor bigint` and `<name>_currency char(3)`.
+ * A single implied currency is a migration nobody wants to write later, and a float is a
+ * rounding bug nobody wants to debug.
+ */
+export const money = () => column('money', parseMoney);
+/** The CHECK that stops a psql session writing a currency the app would refuse. */
+export const currencyCheck = (currencyColumn) => `${currencyColumn} ~ '^[A-Z]{3}$'`;
+//# sourceMappingURL=columns.js.map

package/src/columns.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.js","sourceRoot":"","sources":["columns.ts"],"names":[],"mappings":"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"}

package/src/columns.ts

@@ -1,255 +1,202 @@
-// The blessed column helpers. There is exactly one way to store an id, a timestamp,
-// money, a locale and a time zone — the alternatives (float money, naive timestamps,
-// a single implied currency) are the bugs this file exists to make unreachable.
-import { uuid } from '@ultimat3/core';
-import { invariantViolated } from './errors';
-import type { ColumnDef, ColumnMap, IndexDef, TableDef } from './types';
+// The blessed column builders. There is exactly one way to store an id, an instant, money, a
+// locale and a time zone — the alternatives (float money, naive timestamps, a single implied
+// currency) are the bugs this file exists to make unreachable.
 
-const snake = (value: string): string => value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+import { uuid as uuidV7 } from '@ultimat3/core';
+import { BARE, column, GENERATED_UUID, makeColumn, makeTimestamp } from './column';
+import { invariantViolated } from './errors';
+import type { Column, MoneyInput, MoneyValue, TimestampColumn, UuidColumn } from './types';
 
-const reject = (column: string, rule: string, detail: string): never => {
-  throw invariantViolated(column, rule, detail);
+const reject = (rule: string, detail: string): never => {
+  throw invariantViolated('column', rule, detail);
 };
 
-interface ColumnOptions {
-  readonly name?: string;
-  readonly comment?: string;
-}
-
-const base = <T>(
-  kind: ColumnDef<T>['kind'],
-  parse: (value: unknown) => T,
-  overrides: Partial<ColumnDef<T>> = {},
-): ColumnDef<T> => ({
-  // '' means "derive from the property key in table()", so a column is declared once.
-  name: '',
-  kind,
-  notNull: true,
-  primaryKey: false,
-  unique: false,
-  index: false,
-  parse,
-  ...overrides,
-});
-
-const asString =
-  (label: string) =>
-  (value: unknown): string => {
-    if (typeof value === 'string') return value;
-    return reject(label, 'type', `expected a string, got ${typeof value}`);
-  };
-
-const asDate =
-  (label: string) =>
-  (value: unknown): Date => {
-    if (value instanceof Date) return value;
-    if (typeof value === 'string' || typeof value === 'number') {
-      const parsed = new Date(value);
-      if (!Number.isNaN(parsed.getTime())) return parsed;
-    }
-    return reject(label, 'type', `expected a Date or ISO-8601 string, got ${String(value)}`);
-  };
+/** uuid v7: time-ordered, so a primary key index stays append-friendly. */
+export const newId = (): string => uuidV7();
 
 const UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
 
-const asUuid =
-  (label: string) =>
-  (value: unknown): string => {
-    if (typeof value === 'string' && UUID.test(value)) return value;
-    return reject(label, 'format', `expected a uuid, got ${String(value)}`);
-  };
+const parseUuid = (value: unknown): string =>
+  typeof value === 'string' && UUID.test(value)
+    ? value
+    : reject('format', `expected a uuid, got ${String(value)}`);
+
+export const uuid = (): UuidColumn => ({
+  ...makeColumn<string, false>({ ...BARE, kind: 'uuid' }, parseUuid, false),
+  // Narrower than the generic chain: a uuid key is generated when omitted, so it is the one
+  // primary key an insert may leave out.
+  primaryKey: () =>
+    makeColumn<string, true>(
+      { ...BARE, kind: 'uuid', primaryKey: true, default: GENERATED_UUID },
+      parseUuid,
+      true,
+    ),
+});
 
-/** uuid v7: time-ordered, so a primary key index stays append-friendly. */
-export const newId = (): string => uuid();
-
-export const id = (options: ColumnOptions = {}): ColumnDef<string> =>
-  base<string>('uuid', asUuid('id'), {
-    ...options,
-    name: options.name ?? 'id',
-    primaryKey: true,
-    default: { kind: 'generated', by: 'uuid-v7' },
-  });
-
-export const text = (options: ColumnOptions & { readonly check?: string } = {}) =>
-  base<string>('text', asString(options.name ?? 'text'), options);
-
-const asBoolean =
-  (label: string) =>
-  (value: unknown): boolean =>
-    typeof value === 'boolean'
-      ? value
-      : reject(label, 'type', `expected a boolean, got ${typeof value}`);
+export interface TextOptions {
+  /** Emits `char_length(<column>) <= max`, so Postgres refuses an over-long string too. */
+  readonly max?: number;
+}
 
-const asInteger =
-  (label: string) =>
-  (value: unknown): number =>
+export const text = (options: TextOptions = {}): Column<string> =>
+  column<string>(
+    'text',
+    (value) =>
+      typeof value === 'string' ? value : reject('type', `expected a string, got ${typeof value}`),
+    options.max === undefined
+      ? {}
+      : { length: options.max, check: (name) => `char_length(${name}) <= ${options.max}` },
+  );
+
+export const integer = (): Column<number> =>
+  column<number>('integer', (value) =>
     typeof value === 'number' && Number.isSafeInteger(value)
       ? value
-      : reject(label, 'type', `expected a safe integer, got ${String(value)}`);
+      : reject('type', `expected a safe integer, got ${String(value)}`),
+  );
 
-const asCurrency =
-  (label: string) =>
-  (value: unknown): string =>
-    typeof value === 'string' && /^[A-Z]{3}$/.test(value)
-      ? value
-      : reject(label, 'iso-4217', `expected a 3-letter ISO-4217 code, got ${String(value)}`);
-
-export const boolean = (options: ColumnOptions = {}): ColumnDef<boolean> =>
-  base<boolean>('boolean', asBoolean(options.name ?? 'boolean'), options);
-
-export const integer = (
-  options: ColumnOptions & { readonly check?: string } = {},
-): ColumnDef<number> => base<number>('integer', asInteger(options.name ?? 'integer'), options);
-
-/** UTC always. A `timestamp without time zone` column is not expressible here. */
-export const timestamps = (): {
-  readonly createdAt: ColumnDef<Date>;
-  readonly updatedAt: ColumnDef<Date>;
-} => ({
-  createdAt: base<Date>('timestamptz', asDate('createdAt'), {
-    name: 'created_at',
-    default: { kind: 'generated', by: 'now' },
-    index: true,
-  }),
-  updatedAt: base<Date>('timestamptz', asDate('updatedAt'), {
-    name: 'updated_at',
-    default: { kind: 'generated', by: 'now' },
-  }),
-});
+export const boolean = (): Column<boolean> =>
+  column<boolean>('boolean', (value) =>
+    typeof value === 'boolean' ? value : reject('type', `expected a boolean, got ${typeof value}`),
+  );
 
-export type MoneyColumns<N extends string> = {
-  readonly [K in `${N}Minor`]: ColumnDef<bigint>;
-} & {
-  readonly [K in `${N}Currency`]: ColumnDef<string>;
+const parseInstant = (value: unknown): Date => {
+  if (value instanceof Date && !Number.isNaN(value.getTime())) return value;
+  if (typeof value === 'string' || typeof value === 'number') {
+    const parsed = new Date(value);
+    if (!Number.isNaN(parsed.getTime())) return parsed;
+  }
+  return reject('format', `expected a UTC instant, got ${String(value)}`);
 };
 
-const asMinorUnits =
-  (label: string) =>
-  (value: unknown): bigint => {
-    if (typeof value === 'bigint') return value;
-    if (typeof value === 'number') {
-      if (!Number.isInteger(value)) {
-        return reject(
-          label,
-          'money-minor-units',
-          `got the float ${value}; money is integer minor units — 12.34 EUR is 1234n, not 12.34`,
-        );
-      }
-      return BigInt(value);
-    }
-    if (typeof value === 'string' && /^-?\d+$/.test(value)) return BigInt(value);
-    return reject(label, 'money-minor-units', `expected integer minor units, got ${String(value)}`);
-  };
+/** Always `timestamptz`. UTC storage is not a per-table decision. */
+export const timestamp = (): TimestampColumn =>
+  makeTimestamp<false>({ ...BARE, kind: 'timestamptz' }, parseInstant, false);
+
+const quote = (value: string): string => `'${value.replaceAll("'", "''")}'`;
+
+const oneOf =
+  (values: readonly string[]) =>
+  (name: string): string =>
+    `${name} in (${values.map(quote).join(', ')})`;
 
 /**
- * Two columns, always: minor units as bigint and an ISO-4217 code. A single-currency
- * assumption is a migration nobody wants to write later, and a float is a rounding
- * bug nobody wants to debug.
+ * A closed set of strings, emitted as a CHECK rather than a Postgres `ENUM` type: adding a
+ * variant is then a one-line migration instead of `ALTER TYPE`, which cannot run inside a
+ * transaction on older servers.
  */
-export const money = <N extends string>(name: N): MoneyColumns<N> =>
-  ({
-    [`${name}Minor`]: base<bigint>('bigint', asMinorUnits(`${name}Minor`), {
-      name: `${snake(name)}_minor`,
-    }),
-    [`${name}Currency`]: base<string>('char', asCurrency(`${name}Currency`), {
-      name: `${snake(name)}_currency`,
-      length: 3,
-      check: `${snake(name)}_currency ~ '^[A-Z]{3}$'`,
-    }),
-  }) as unknown as MoneyColumns<N>;
-
-/** IANA identifier, validated by `Intl` at write time and by a CHECK in the database. */
-export const tz = (options: ColumnOptions = {}): ColumnDef<string> => {
-  const label = options.name ?? 'tz';
-  return base<string>(
+export const enumerated = <const V extends readonly string[]>(values: V): Column<V[number]> => {
+  const allowed = new Set<string>(values);
+  return column<V[number]>(
+    'text',
+    (value) =>
+      typeof value === 'string' && allowed.has(value)
+        ? value
+        : reject('enum', `expected one of ${values.join(' | ')}, got ${String(value)}`),
+    { values, check: oneOf(values) },
+  );
+};
+
+/**
+ * An absolute http(s) URL, validated on write rather than on render: a bad URL stored once is
+ * served to every reader, and `<img src>` fails silently in the browser.
+ */
+export const url = (): Column<string> =>
+  column<string>(
     'text',
     (value) => {
       if (typeof value === 'string') {
         try {
-          new Intl.DateTimeFormat('en', { timeZone: value }).format(0);
-          return value;
+          const parsed = new URL(value);
+          if (parsed.protocol === 'http:' || parsed.protocol === 'https:') return value;
         } catch {
-          return reject(label, 'iana-tz', `${value} is not an IANA time zone`);
+          // fall through to the shared rejection so the error names the rule
         }
       }
-      return reject(label, 'iana-tz', `expected an IANA time zone, got ${typeof value}`);
+      return reject('format', `expected an absolute http(s) URL, got ${String(value)}`);
     },
-    { ...options, check: `${snake(label)} ~ '^[A-Za-z0-9_+/-]{3,64}$'` },
+    { check: (name) => `${name} ~ '^https?://'` },
   );
+
+const isIanaZone = (value: string): boolean => {
+  try {
+    new Intl.DateTimeFormat('en', { timeZone: value }).format(0);
+    return true;
+  } catch {
+    return false;
+  }
 };
 
-export const locale = (options: ColumnOptions = {}): ColumnDef<string> => {
-  const label = options.name ?? 'locale';
-  return base<string>('text', asString(label), {
-    ...options,
-    check: `${snake(label)} ~ '^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$'`,
-  });
+/**
+ * IANA identifiers, checked against `Intl` when the column is declared — a typo or a UTC offset
+ * is a startup error rather than a row nobody can format. An offset is wrong twice a year.
+ */
+export const tz = <const Z extends readonly string[]>(zones: Z): Column<Z[number]> => {
+  for (const zone of zones) {
+    if (!isIanaZone(zone)) reject('iana-tz', `${zone} is not an IANA time zone`);
+  }
+  const allowed = new Set<string>(zones);
+  return column<Z[number]>(
+    'text',
+    (value) =>
+      typeof value === 'string' && allowed.has(value)
+        ? value
+        : reject('iana-tz', `expected one of ${zones.join(' | ')}, got ${String(value)}`),
+    { values: zones, check: oneOf(zones) },
+  );
 };
 
-export const slug = (options: ColumnOptions = {}): ColumnDef<string> => {
-  const label = options.name ?? 'slug';
-  return base<string>('text', asString(label), {
-    ...options,
-    unique: true,
-    check: `${snake(label)} ~ '^[a-z0-9]+(-[a-z0-9]+)*$'`,
-  });
+const BCP47 = /^[a-z]{2,3}(-[A-Za-z0-9]{2,8})*$/;
+
+export const locale = <const L extends readonly string[]>(locales: L): Column<L[number]> => {
+  for (const tag of locales) {
+    if (!BCP47.test(tag)) reject('bcp-47', `${tag} is not a BCP-47 language tag`);
+  }
+  const allowed = new Set<string>(locales);
+  return column<L[number]>(
+    'text',
+    (value) =>
+      typeof value === 'string' && allowed.has(value)
+        ? value
+        : reject('bcp-47', `expected one of ${locales.join(' | ')}, got ${String(value)}`),
+    { values: locales, check: oneOf(locales) },
+  );
 };
 
-/** Takes its own parser: a jsonb column without a schema is an untyped hole. */
-export const jsonb = <T>(parse: (value: unknown) => T, options: ColumnOptions = {}): ColumnDef<T> =>
-  base<T>('jsonb', parse, options);
-
-/** Presence of this column is what makes an entity soft-deletable — not a flag. */
-export const softDelete = (): { readonly deletedAt: ColumnDef<Date | null> } => ({
-  deletedAt: base<Date | null>(
-    'timestamptz',
-    (value) => (value === null || value === undefined ? null : asDate('deletedAt')(value)),
-    { name: 'deleted_at', notNull: false, index: true },
-  ),
-});
+const parseMinor = (value: unknown): bigint => {
+  if (typeof value === 'bigint') return value;
+  if (typeof value === 'number') {
+    if (!Number.isInteger(value)) {
+      return reject(
+        'money-minor-units',
+        `got the float ${value}; money is integer minor units — 12.34 EUR is 1234n, not 12.34`,
+      );
+    }
+    return BigInt(value);
+  }
+  if (typeof value === 'string' && /^-?\d+$/.test(value)) return BigInt(value);
+  return reject('money-minor-units', `expected integer minor units, got ${String(value)}`);
+};
 
-/** Presence of this column is what makes an entity tenant-scoped. See tenancy.ts. */
-export const orgId = (options: ColumnOptions & { readonly table?: string } = {}) =>
-  base<string>('uuid', asUuid('orgId'), {
-    name: options.name ?? 'org_id',
-    index: true,
-    references: { table: options.table ?? 'orgs', column: 'id', onDelete: 'cascade' },
-  });
-
-export const nullable = <T>(column: ColumnDef<T>): ColumnDef<T | null> => ({
-  ...column,
-  notNull: false,
-  parse: (value) => (value === null || value === undefined ? null : column.parse(value)),
-});
+const parseCurrency = (value: unknown): string =>
+  typeof value === 'string' && /^[A-Z]{3}$/.test(value)
+    ? value
+    : reject('iso-4217', `expected a 3-letter ISO-4217 code, got ${String(value)}`);
 
-export const references = <T>(column: ColumnDef<T>, target: string, targetColumn = 'id') => ({
-  ...column,
-  index: true,
-  references: { table: target, column: targetColumn },
-});
+const parseMoney = (value: unknown): MoneyValue => {
+  if (typeof value !== 'object' || value === null) {
+    return reject('money', `expected { minor, currency }, got ${String(value)}`);
+  }
+  const input: Partial<MoneyInput> = value;
+  return { minor: parseMinor(input.minor), currency: parseCurrency(input.currency) };
+};
 
 /**
- * Composes columns into a table, filling every column name that was left to the
- * property key (`orgId` -> `org_id`) so a physical name is written at most once.
+ * One property, two physical columns: `<name>_minor bigint` and `<name>_currency char(3)`.
+ * A single implied currency is a migration nobody wants to write later, and a float is a
+ * rounding bug nobody wants to debug.
  */
-export const table = <C extends ColumnMap>(name: string, columns: C): TableDef<C> => {
-  const resolved: Record<string, ColumnDef<unknown>> = {};
-  const primaryKey: string[] = [];
-  const indexes: IndexDef[] = [];
-  for (const [property, column] of Object.entries(columns)) {
-    const physical = column.name === '' ? snake(property) : column.name;
-    resolved[property] = { ...column, name: physical };
-    if (column.primaryKey) primaryKey.push(physical);
-    if (column.unique) {
-      indexes.push({ name: `${name}_${physical}_key`, columns: [physical], unique: true });
-    } else if (column.index) {
-      indexes.push({ name: `${name}_${physical}_idx`, columns: [physical], unique: false });
-    }
-  }
-  return {
-    name,
-    columns: resolved as unknown as C,
-    primaryKey: primaryKey.length > 0 ? primaryKey : ['id'],
-    indexes,
-  };
-};
+export const money = (): Column<MoneyValue> => column<MoneyValue>('money', parseMoney);
+
+/** The CHECK that stops a psql session writing a currency the app would refuse. */
+export const currencyCheck = (currencyColumn: string): string => `${currencyColumn} ~ '^[A-Z]{3}$'`;