@zmdb/schema 1.0.0-beta.1

package/package.json

@@ -0,0 +1,82 @@
+{
+  "name": "@zmdb/schema",
+  "version": "1.0.0-beta.1",
+  "description": "Schema DSL + compile-time type derivation (Entity/Create/Update/read DTOs), relations, OpenAPI, and custom types — the single source of truth for a zmdb data layer.",
+  "keywords": [
+    "dto",
+    "openapi",
+    "orm",
+    "schema",
+    "type-derivation",
+    "typescript",
+    "zmdb"
+  ],
+  "homepage": "https://github.com/ambasta/zmdb#readme",
+  "bugs": {
+    "url": "https://github.com/ambasta/zmdb/issues"
+  },
+  "license": "GPL-3.0-or-later",
+  "author": "zmdb contributors",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ambasta/zmdb.git",
+    "directory": "packages/schema"
+  },
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./tags": {
+      "types": "./dist/tags/index.d.ts",
+      "import": "./dist/tags/index.js"
+    },
+    "./ir": {
+      "types": "./dist/ir/index.d.ts",
+      "import": "./dist/ir/index.js"
+    },
+    "./derive": {
+      "types": "./dist/derive/index.d.ts",
+      "import": "./dist/derive/index.js"
+    },
+    "./dto": {
+      "types": "./dist/dto/index.d.ts",
+      "import": "./dist/dto/index.js"
+    },
+    "./naming": {
+      "types": "./dist/naming/index.d.ts",
+      "import": "./dist/naming/index.js"
+    },
+    "./relations": {
+      "types": "./dist/relations/index.d.ts",
+      "import": "./dist/relations/index.js"
+    },
+    "./entity-modeling": {
+      "types": "./dist/entity-modeling/index.d.ts",
+      "import": "./dist/entity-modeling/index.js"
+    },
+    "./openapi": {
+      "types": "./dist/openapi/index.d.ts",
+      "import": "./dist/openapi/index.js"
+    },
+    "./custom-types": {
+      "types": "./dist/custom-types/index.d.ts",
+      "import": "./dist/custom-types/index.js"
+    }
+  },
+  "publishConfig": {
+    "access": "public",
+    "tag": "beta"
+  },
+  "scripts": {
+    "build": "node ../../scripts/build-package.mjs",
+    "test": "vitest run"
+  },
+  "engines": {
+    "node": ">=26"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts"
+}

package/src/custom-types/index.ts

@@ -0,0 +1,59 @@
+// Custom types & codecs — see ./SPEC.md.
+
+import { type Codec } from '../ir/index.js';
+
+/**
+ * A column type the library does not know, described by its owner.
+ *
+ * Three types, because a column has three (plan D3): `Wire` is what JSON carries,
+ * `TS` is what handler code holds, and `DB` is what the driver binds. A codec that
+ * named only two of them left the third to be guessed, and the guess was "the same
+ * as the app type" — which is how a `Money` instance ended up being handed to
+ * `JSON.stringify` and to a query parameter unchanged.
+ *
+ * All four functions are required. A codec whose `toWire` was optional would be a
+ * codec that sometimes converts, and the caller cannot tell which kind it has.
+ */
+export interface CustomType<Wire, TS, DB = unknown> {
+  /** DDL type, e.g. `'jsonb'`. Dialect spelling is the emitter's business. */
+  readonly sqlType: string;
+  /** Serialise for the driver. */
+  readonly toDb: (value: TS) => DB;
+  /** Parse a driver row value. */
+  readonly fromDb: (raw: DB) => TS;
+  /** Serialise for a JSON response. */
+  readonly toWire: (value: TS) => Wire;
+  /** Parse a JSON request body value. */
+  readonly fromWire: (raw: Wire) => TS;
+}
+
+export function defineType<Wire, TS, DB>(def: CustomType<Wire, TS, DB>): CustomType<Wire, TS, DB> {
+  return Object.freeze({ ...def });
+}
+export function encodeValue<Wire, TS, DB>(type: CustomType<Wire, TS, DB>, value: TS): DB {
+  return type.toDb(value);
+}
+export function decodeValue<Wire, TS, DB>(type: CustomType<Wire, TS, DB>, raw: DB): TS {
+  return type.fromDb(raw);
+}
+
+/**
+ * Adapt a `CustomType` to the `Codec` the IR's wire crossing asks for.
+ *
+ * The IR speaks `unknown` on both sides because it is data, not generics; the
+ * conversion is one cast at this boundary rather than one at every registry literal.
+ * A `Codec<'Money'>` tag names the key this goes under:
+ *
+ * ```ts
+ * wireDecoder(Schema, 'create', { Money: wireCodec(MoneyType) })
+ * ```
+ */
+export function wireCodec<Wire, TS, DB>(type: CustomType<Wire, TS, DB>): Codec {
+  // boundary: a registry is keyed by name, so the value arriving at either direction is only
+  // as typed as the declaration that named this codec. The validator is what proves it, and
+  // it runs before `decode` and after `encode`.
+  return {
+    decode: (wire: unknown) => type.fromWire(wire as Wire),
+    encode: (app: unknown) => type.toWire(app as TS),
+  };
+}

package/src/derive/index.ts

@@ -0,0 +1,224 @@
+// @zmdb/schema/derive: the DTO suite, derived from a tagged type.
+//
+// There is one `Entity`, one `CreateDTO`, one `UpdateDTO`, one `PrimaryKeyOf`, and they
+// are these. `../index.ts` re-exports them under the same names it used to define
+// schema-value twins under; the twins are deleted, not deprecated.
+//
+// Every derivation takes the declared type and nothing else. Nothing here tests
+// `T extends { columns: ... }`, nothing dispatches on whether it was handed a value, and
+// so nothing pays for that test per use. A caller who holds a schema value crosses back
+// at a boundary — `TaggedSchema<T>` in a parameter position, `T` by inference — and the
+// derivations never see the value at all.
+
+import {
+  type AnyRelation,
+  type HasDefault,
+  type PrimaryKey,
+  type Sensitive,
+  type Serial,
+  type SoftDelete,
+  type Sql,
+  type Table,
+  type Unique,
+  type WireAs,
+} from '../tags/index.js';
+
+/**
+ * What every derivation takes: a type that could have been declared as a table.
+ *
+ * An alias for `Table<string>`, and the constraint is the point. `Table` is an
+ * all-optional weak type, so TypeScript's weak-type rule rejects anything with no property
+ * in common with it — which a generated schema *value* is. `Entity<typeof UserSchema>`, the
+ * spelling this design replaced, is therefore a compile error rather than the schema's own
+ * five properties dressed up as a row. Worth constraining for precisely because the wrong
+ * answer was structurally plausible: it had keys and it had types, so nothing downstream
+ * would have complained.
+ *
+ * An index-signature row still passes, because a string index can hold the slot — see
+ * `dto/index.ts`'s `UnknownRow`, the one corner of the query surface keyed by a table
+ * *name* instead of by a declaration.
+ */
+export type DeclaredTable = Table<string>;
+
+// ---------------------------------------------------------------------------
+// Key filters.
+// ---------------------------------------------------------------------------
+//
+// `NonNullable<T[K]>` rather than a bare `T[K]` is load-bearing. A nullable
+// column with a default is declared `(string & HasDefault) | null`, and `null` is
+// not assignable to a weak object type, so the union as a whole does not match
+// `HasDefault`. Testing the non-nullable arm is what makes a nullable defaulted
+// column optional on insert instead of required. `tagged-dto.type-test.ts` pins
+// this down: it is exactly the sort of thing that silently returns `never`.
+//
+// `-?` strips optionality from the probe so an already-optional property is still
+// examined under `exactOptionalPropertyTypes`.
+//
+// Symbol keys are filtered out everywhere below: entity-level tags (`Table`,
+// `Fts`, `SoftDelete`, `ForeignKey`) arrive through `extends` and would
+// otherwise show up in `keyof`.
+
+export type KeysCarrying<T, Tag> = {
+  [K in keyof T]-?: NonNullable<T[K]> extends Tag ? (K extends string ? K : never) : never;
+}[keyof T];
+
+/** Columns the database generates. Omitted from `CreateDTO` outright. */
+export type SerialKeys<T> = KeysCarrying<T, Serial>;
+/** Columns with a database default. Optional on insert, not absent. */
+export type DefaultKeys<T> = KeysCarrying<T, HasDefault>;
+export type PrimaryKeyKeys<T> = KeysCarrying<T, PrimaryKey>;
+export type SensitiveKeys<T> = KeysCarrying<T, Sensitive>;
+export type UniqueKeys<T> = KeysCarrying<T, Unique>;
+/** The entity-level soft-delete tag names one managed column. */
+export type SoftDeleteKeys<T> = T extends SoftDelete<infer Column> ? Extract<Column, ColumnKeys<T>> : never;
+/** Columns whose declared type admits `null`. Native, not a tag. */
+export type NullableKeys<T> = { [K in keyof T]-?: null extends T[K] ? (K extends string ? K : never) : never }[keyof T];
+
+/**
+ * Properties declared with a relation tag: a join target, not a column.
+ *
+ * These have to come out of `Entity<T>`, and therefore out of everything derived
+ * from it. A relation left in would be a column to `INSERT`, a column to `SELECT`
+ * and a JSON Schema property, none of which it is. `./query.ts` puts them back where
+ * they belong, in `Populated<T, K>`.
+ */
+export type RelationKeys<T> = KeysCarrying<T, AnyRelation>;
+
+/**
+ * Everything that is a column: a data key that is not a relation.
+ *
+ * Spelled as its own projection rather than as a subtraction. `Exclude<AllKeys<T>,
+ * RelationKeys<T>>` does not compile: for an unresolved `T` both operands normalise to
+ * the same deferred expression, so the subtraction yields `never`, and then
+ * `Pick<Entity<T>, DefaultKeys<T>>` is an error because nothing is a key of an entity
+ * with no keys.
+ */
+export type ColumnKeys<T> = {
+  [K in keyof T]-?: NonNullable<T[K]> extends AnyRelation ? never : K extends string ? K : never;
+}[keyof T];
+
+// ---------------------------------------------------------------------------
+// The DTO suite.
+// ---------------------------------------------------------------------------
+
+/**
+ * The selectable row: every column, required, sensitive columns included, tags
+ * preserved. Tags must survive here or the constraints would not survive `Omit`
+ * and `Partial` downstream.
+ *
+ * Relations are not columns and are not here. See `RelationKeys`.
+ */
+export type Entity<T extends DeclaredTable> = { -readonly [K in ColumnKeys<T>]-?: T[K] };
+
+/**
+ * A tag filter's keys, narrowed to the keys `Entity<T>` actually has.
+ *
+ * `SerialKeys<T>` and friends are subsets of `ColumnKeys<T>` by construction — a
+ * relation cannot carry `Serial` — but TypeScript will not take it on trust. Relating
+ * two of these projections for an unresolved `T` works only while the *target*'s
+ * template is unconditional, which `DataKeys<T>` was and `ColumnKeys<T>` is not. So the
+ * subset is stated as an intersection, which is assignable to either side by
+ * definition, rather than proved. Nothing changes for a concrete type.
+ */
+type AsColumns<T extends DeclaredTable, K> = K & keyof Entity<T>;
+
+/**
+ * Insert shape. `Serial` columns are **absent** — naming one is a compile error,
+ * because the database generates the value. `HasDefault` columns are **present
+ * and optional**, because supplying one is legitimate. That distinction is the
+ * whole reason the two tags are separate.
+ *
+ * A nullable column is optional for the same reason a defaulted one is: omitting it
+ * inserts `NULL`, which is exactly what passing `null` does, so demanding the key adds
+ * ceremony and no information. The published document has always said this — a nullable
+ * column has never appeared in a `create` document's `required` — and so did the
+ * repository's runtime check. Requiring `bio: null` in the type while the contract said
+ * it was optional meant a client that followed the contract wrote a payload the type
+ * rejected, which is the disagreement this phase exists to remove. It stays *present* and
+ * optional rather than absent, because passing `null` explicitly is legitimate.
+ */
+type OptionalCreateKeys<T extends DeclaredTable> = Exclude<DefaultKeys<T> | NullableKeys<T>, SoftDeleteKeys<T>>;
+
+export type CreateDTO<T extends DeclaredTable> = Omit<
+  Entity<T>,
+  SerialKeys<T> | DefaultKeys<T> | NullableKeys<T> | SoftDeleteKeys<T>
+> &
+  Partial<Pick<Entity<T>, AsColumns<T, OptionalCreateKeys<T>>>>;
+
+/** Patch shape: identity and framework-managed columns dropped, everything else optional. */
+export type UpdateDTO<T extends DeclaredTable> = Partial<
+  Omit<Entity<T>, SerialKeys<T> | PrimaryKeyKeys<T> | SoftDeleteKeys<T>>
+>;
+
+/**
+ * What a read endpoint may return. `Sensitive` columns are removed from the
+ * type, so a leak is a compile error rather than a serializer's responsibility.
+ */
+export type ReadDTO<T extends DeclaredTable> = Omit<Entity<T>, SensitiveKeys<T>>;
+
+type IsUnion<T, U = T> = T extends unknown ? ([U] extends [T] ? false : true) : never;
+
+/**
+ * The key value: a scalar for a single-column key, an object map for a composite
+ * one, `unknown` when the type declares no primary key.
+ *
+ * Named `PrimaryKeyOf` so the tag can be `PrimaryKey`, which is the name typed at
+ * every declaration site (plan D1).
+ */
+export type PrimaryKeyOf<T extends DeclaredTable> = [PrimaryKeyKeys<T>] extends [never]
+  ? unknown
+  : IsUnion<PrimaryKeyKeys<T>> extends true
+    ? { [K in PrimaryKeyKeys<T>]: Entity<T>[AsColumns<T, K>] }
+    : Entity<T>[AsColumns<T, PrimaryKeyKeys<T>>];
+
+// ---------------------------------------------------------------------------
+// The wire shape (plan D3).
+// ---------------------------------------------------------------------------
+//
+// A column has three types: wire (what arrives over HTTP), app (what handler code
+// sees) and db (what the dialect declares). `Entity<T>` is the app type. `Wire<T>`
+// is what a JSON body actually contains, which for a timestamp is an ISO-8601
+// string, never a `Date` — a `Date` cannot survive JSON. The web pipeline decodes
+// wire → app once at the boundary so handlers keep seeing `Date`.
+//
+// A column whose type the library does not know says its own wire form with
+// `WireAs<W>`, and that beats the SQL-type rules: a codec can put anything it likes on
+// the wire, and only the declaration knows what.
+
+// A column's nullability belongs to the column, not to the layer: a `timestamp | null`
+// is a `string | null` on the wire. Factored out so each layer rule below is one line
+// and the three cannot drift apart.
+type OrNull<V, W> = null extends V ? W | null : W;
+
+type WireValue<V> =
+  NonNullable<V> extends WireAs<infer W>
+    ? OrNull<V, W>
+    : NonNullable<V> extends Sql<'timestamp'>
+      ? OrNull<V, string>
+      : NonNullable<V> extends Sql<'bigint'>
+        ? OrNull<V, string>
+        : V;
+
+/** The over-the-wire shape of an entity: JSON-representable throughout. */
+export type Wire<T> = { -readonly [K in ColumnKeys<T>]-?: WireValue<T[K]> };
+
+/** The over-the-wire shape of an insert payload. */
+export type WireCreateDTO<T extends DeclaredTable> = { [K in keyof CreateDTO<T>]: WireValue<CreateDTO<T>[K]> };
+
+// The read/query surface — `WhereDTO`, `OrderByDTO`, `PaginationDTO`, `Projection`,
+// `GetDTO`, `ListDTO`, `Populated`, `JoinRow` — is in `./query.ts`, re-exported here
+// so `@zmdb/schema/derive` is one import.
+export type {
+  GetDTO,
+  GetOptions,
+  JoinRow,
+  ListDTO,
+  ListResult,
+  OrderByDTO,
+  PaginationDTO,
+  Populated,
+  PopulatedEntity,
+  Projection,
+  RelationPath,
+  WhereDTO,
+} from './query.js';

package/src/derive/query.ts

@@ -0,0 +1,128 @@
+// @zmdb/schema/derive/query — the relation-aware half of the read surface.
+//
+// This file used to restate the whole query DTO family, because there were two of them:
+// `../dto/index.ts` was keyed by the schema value and these were keyed by the declared
+// type. There is one family now — `WhereDTO`, `OrderByDTO`, `PaginationDTO`, `Projection`,
+// `GetOptions`, `GetDTO` and `ListDTO` all take the declared type, and they live in
+// `../dto/index.ts` alongside the operator vocabulary and the runtime folders that read
+// them. Two copies of `WhereDTO` were two operator sets to keep in step; the copy is gone
+// and the names below are re-exports, so importing from either path is the same type.
+//
+// What is genuinely *here* is the three shapes that need a relation: a populated row and
+// the two spellings of a join row. Those read `RelationKeys<T>` and the relation tags off
+// the declaration, which is something only a declared type can answer — a schema value
+// carries no relations at all, which is why the version of `Populated` this replaced had
+// to rebuild the cardinality out of a `RelationMeta` through six nested conditionals.
+
+import { type DeclaredTable, type Entity, type RelationKeys } from './index.js';
+
+export {
+  type GetDTO,
+  type GetOptions,
+  type ListDTO,
+  type ListResult,
+  type OrderByDTO,
+  type PaginationDTO,
+  type Projection,
+  type WhereDTO,
+} from '../dto/index.js';
+
+// ---------------------------------------------------------------------------
+// Relations.
+// ---------------------------------------------------------------------------
+//
+// `K & keyof T` throughout: `RelationKeys<T>` *is* a subset of `keyof T` by
+// construction, but it is produced by a mapped-type projection and TypeScript does not
+// carry that fact forward, so an unqualified `T[K]` does not compile.
+
+/**
+ * What a populated relation holds: fetched rows, and what happens when nothing matched.
+ *
+ * Cardinality comes from the declaration and nothing else, which is the point: `comments?:
+ * Comment[] & OneToMany<…>` is an array because it was written as one, and `author?: User &
+ * ManyToOne<…>` is not. The schema-value version had to read the cardinality out of a
+ * `RelationMeta` and rebuild the array, through six nested conditional types named
+ * `RelationEntityFromDef` and `RelationCardinalityFromDef`, because a relation *value* does
+ * not carry the target's type. Both are deleted.
+ *
+ * Without a nested path, the target becomes `Entity<>`: its own relations are absent.
+ * A nested path adds only its requested descendants, using this same derivation.
+ * And a to-one gains `| null`, because a foreign key that matches nothing is a row the
+ * database can hold — `null` is what the repository attaches for it, and a type that said
+ * `User` there would be wrong for the case the query cannot rule out. A to-many needs no
+ * such arm: no match is the empty array.
+ */
+type PopulatedValue<V, Paths extends string> =
+  NonNullable<V> extends readonly (infer E)[]
+    ? readonly ([Paths] extends [never] ? Entity<E & DeclaredTable> : PopulatedRow<E & DeclaredTable, Paths>)[]
+    :
+        | ([Paths] extends [never]
+            ? Entity<NonNullable<V> & DeclaredTable>
+            : PopulatedRow<NonNullable<V> & DeclaredTable, Paths>)
+        | null;
+
+/** Validate a supplied path without expanding every path of a recursive entity graph. */
+export type RelationPath<T extends DeclaredTable, Path extends string> = Path extends `${infer Head}.${infer Tail}`
+  ? Head extends RelationKeys<T>
+    ? `${Head}.${RelationPath<RelationTargetOf<T[Head & keyof T]>, Tail>}`
+    : never
+  : Path extends RelationKeys<T>
+    ? Path
+    : never;
+
+type PathHead<Path extends string> = Path extends `${infer Head}.${string}` ? Head : Path;
+type PathTail<Path extends string, Head extends string> = Path extends `${Head}.${infer Tail}` ? Tail : never;
+type RootRelationPath<T> = (RelationKeys<T> & string) | `${RelationKeys<T> & string}.${string}`;
+
+/**
+ * The row plus the relation paths named by `K`, populated.
+ *
+ * Dotted paths contribute their first segment to this row and pass their remaining
+ * segments to the child. Keeping direct keys in the mapped key set also lets a generic
+ * one-level relation loader index the result with its declared relation key.
+ */
+type PopulatedRow<T extends DeclaredTable, K extends string> = Entity<T> & {
+  -readonly [P in (K | PathHead<K>) & keyof T]: PopulatedValue<T[P], PathTail<K, P & string>>;
+};
+
+export type PopulatedEntity<
+  T extends DeclaredTable,
+  K extends RootRelationPath<T> = RelationKeys<T> & string,
+> = PopulatedRow<T, K> & ([Exclude<K, RelationPath<T, K>>] extends [never] ? unknown : never);
+
+/** Alias kept because both names are in use across the repository and the docs. */
+export type Populated<
+  T extends DeclaredTable,
+  K extends RootRelationPath<T> = RelationKeys<T> & string,
+> = PopulatedEntity<T, K>;
+
+/**
+ * The target of a relation: the element type for a to-many, the type itself for a to-one.
+ *
+ * `& DeclaredTable` on the way out rather than a constraint on the way in. A relation is
+ * declared as `Comment[] & OneToMany<…>`, so the element type is whatever the author wrote
+ * there and TypeScript cannot be told in advance that it is a table — but `Entity<>` wants
+ * to know, and intersecting is assignable by definition where proving is not.
+ */
+type RelationTargetOf<V> = (NonNullable<V> extends readonly (infer E)[] ? E : NonNullable<V>) & DeclaredTable;
+
+/**
+ * One row of a join: the base row's columns and the target's, flat.
+ *
+ * A `LEFT JOIN` can produce a row with no match, so the joined half is `Partial`. An
+ * `INNER JOIN` cannot, so it is not — and that asymmetry is the whole reason `Kind` is
+ * a parameter rather than always-partial.
+ *
+ * `../relations/index.ts` exports the same asymmetry as `JoinRow<Base, Joined, Kind>`, for
+ * the join that names its target directly instead of by a relation. Two shapes, because they
+ * take different arguments: that one is given both tables, this one is given a base table and
+ * the name of one of its relations. The conditional itself is two lines and duplicating it is
+ * cheaper than a shared helper neither would read more clearly.
+ */
+export type JoinRow<
+  T extends DeclaredTable,
+  K extends RelationKeys<T>,
+  Kind extends 'inner' | 'left' = 'left',
+> = Kind extends 'inner'
+  ? Entity<T> & Entity<RelationTargetOf<T[K & keyof T]>>
+  : Entity<T> & Partial<Entity<RelationTargetOf<T[K & keyof T]>>>;