@ultimat3/entity 0.0.1 → 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 developerz.ai
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,60 +1,144 @@
 # @ultimat3/entity 🗄️
 
-An entity is **a table + its domain type + its invariants**. The first of the eight
-primitives; repos, admin screens, cache tags and the manifest are all derived from
-one `entity()` call.
+An entity is **columns + the invariants that hold for every row**. The row type is derived from
+the columns: `type Post = typeof posts.$row`. Declare the shape once — repos, migrations, the
+admin screen, cache tags and the manifest are all projections of that one call.
 
 ```ts
-const posts = entity({
-  table: table('posts', { id: id(), orgId: orgId(), title: text(), ...money('price'),
-                          ...timestamps(), ...softDelete() }),
-  type: Post,
-  invariants: [invariant('title_not_empty', {
-    message: 'title must not be empty',
-    sql: 'char_length(title) > 0',
-    holds: (p) => p.title.length > 0,
-  })],
+import {
+  entity, enumerated, integer, invariant, text, timestamp, url, uuid,
+} from '@ultimat3/entity';
+
+export const posts = entity('posts', {
+  tenant: 'orgId',
+  columns: {
+    id: uuid().primaryKey(),
+    orgId: uuid().references(() => orgs.id, { onDelete: 'cascade' }),
+    slug: text({ max: 80 }),
+    title: text({ max: 120 }),
+    coverUrl: url().nullable(),
+    status: enumerated(POST_STATUSES).default('draft'),
+    likeCount: integer().default(0),
+    createdAt: timestamp().defaultNow(),
+    updatedAt: timestamp().defaultNow().onUpdateNow(),
+  },
+  invariants: [
+    invariant('post_title_present', (c) => c.title.trimmed().minLength(1)),
+    invariant('post_slug_unique_per_org', (c) => c.unique(['orgId', 'slug'])),
+    invariant('post_like_count_non_negative', (c) => c.likeCount.atLeast(0)),
+  ],
+  indexes: [{ on: ['orgId', 'createdAt'], order: 'desc', where: (c) => c.status.eq('published') }],
 });
+
+export type Post = typeof posts.$row;
+
+export const PostView = posts.$view(['id', 'title', 'coverUrl', 'status']);
+export type PostView = typeof PostView.$row;
 ```
 
+## `$view` is what leaves the server
+
+`posts.$view([...])` returns a Standard Schema over a subset of the row, so an action names it
+directly — `output: PostView` — and the projected type flows on to the client and the component.
+
+| Rule | Detail |
+|---|---|
+| Keys are checked twice | unknown key ⇒ `tsc` error, and `X_INVARIANT_VIOLATED` at declaration for a JS caller |
+| Values are the columns' | each key is parsed by the column that declared it; no second copy of the rule |
+| Nothing is invented | a view projects a row that exists — an absent required key is missing data, not a default |
+| `$name` | `posts.view.id_title_coverUrl_status` — stable, and legal as an OpenAPI `components.schemas` key |
+
+There is no free `view(posts, [...])` function: a projection is reached through the entity, and
+every framework member is `$`-prefixed so a column may still be called `name`, `view` or `tenant`.
+
+A view the columns cannot express — a joined `authorName`, a computed `excerpt` — is a hand-written
+`t.object({...})`. `t` is re-exported here, the same object `@ultimat3/schema` exports, so that file
+still imports one package: `import { entity, t } from '@ultimat3/entity'`.
+
 ## Blessed columns
 
-| Helper | Emits | Why it is the only way |
+| Builder | Emits | Why it is the only way |
 |---|---|---|
-| `id()` | `uuid` pk, v7 default | time-ordered keys keep the pk index append-friendly |
-| `timestamps()` | `created_at`/`updated_at` `timestamptz` | UTC storage is not a per-table decision |
-| `money('price')` | `price_minor bigint` + `price_currency char(3)` | never a float, never one implied currency |
-| `tz()` | `text` + regex CHECK, `Intl`-validated | an offset is not a time zone |
-| `locale()`, `slug()` | `text` + CHECK | format is enforced by the database too |
-| `orgId()` | `uuid` + FK + index | its presence is what turns on tenancy |
-| `softDelete()` | `deleted_at timestamptz null` | its presence is what turns on soft delete |
-| `jsonb(parse)` | `jsonb` | a jsonb column without a parser is an untyped hole |
-
-Physical names are derived from the property key (`orgId` → `org_id`); write a name
-once or not at all.
+| `uuid()` | `uuid`; `.primaryKey()` defaults to v7 | time-ordered keys keep the pk index append-friendly |
+| `timestamp()` | `timestamptz` | UTC storage is not a per-table decision; there is no naive variant |
+| `money()` | `<name>_minor bigint` + `<name>_currency char(3)` | never a float, never one implied currency |
+| `enumerated(v)` | `text` + CHECK | a variant is a one-line migration, not `ALTER TYPE` |
+| `tz(zones)`, `locale(tags)` | `text` + CHECK, `Intl`-validated at declaration | an offset is not a time zone |
+| `text({ max })`, `integer()`, `boolean()`, `url()` | `text`/`integer`/`boolean` + CHECK | format is enforced by the database too |
+
+Chain: `.primaryKey()` · `.nullable()` · `.unique()` · `.default(v)` · `.defaultNow()` ·
+`.onUpdateNow()` · `.references(() => other.id, { onDelete })` · `.tenant()`. Physical names are
+derived from the property key (`orgId` → `org_id`); a name is written once, or never.
 
 ## Invariants run twice
 
-Written once, enforced in the app on every write **and** in Postgres as a CHECK or a
-unique index (`toSql()`). The database can never disagree with the code — a bulk
-import or a `psql` session hits the same rule.
+One declaration, two enforcement points: the app checks it on every write, and the migration
+emits it. A bulk import or a `psql` session hits the same rule.
 
 ```sql
-ALTER TABLE "posts" ADD CONSTRAINT "posts_title_not_empty_check" CHECK (char_length(title) > 0);
+ALTER TABLE "posts" ADD CONSTRAINT "posts_post_like_count_non_negative_check" CHECK (like_count >= 0);
+CREATE UNIQUE INDEX "posts_post_slug_unique_per_org_key" ON "posts" ("org_id", "slug");
 ```
 
-## Repositories
+A rule written as a JS predicate — `c.slug.matches(isValidSlug)`, `c.satisfies(fn, [...])` —
+still runs on write, reports `kind: 'assert'` and `sql: null`, and is what `x verify` warns
+about: a rule the database does not know is a rule a migration script can violate.
+
+## One typed handle
+
+```ts
+export const db = database({ orgs, posts });
+
+db.posts.where({ orgId }).orderBy('createdAt').limit(50).page(); // { rows, nextCursor }
+```
 
-`Repo<T>` takes an explicit `tx` on every write so the transactional outbox can join
-the request's transaction. Pagination is **cursor-only**: `OFFSET` is wrong under
-concurrent writes because an insert before the offset shifts every later page, so a
-client silently skips and repeats rows. `memoryRepo()` is the default driver
-(tests, `x dev` before the first migration); Drizzle + Postgres is production.
+`db.posts` exists because `posts` was declared. Pagination is **cursor-only**: `OFFSET` is wrong
+under concurrent writes, because an insert before the offset shifts every later page and the
+client silently skips and repeats rows.
+
+`nextCursor` is signed by `@ultimat3/core` and scoped to the plan that produced it — this entity,
+these filters, this sort order. A tampered cursor, or one taken from another listing, is
+`X_CURSOR_INVALID` rather than a silent page one. The page size is deliberately outside the scope:
+asking for a bigger next page is the same query.
+
+## Two drivers, one meaning
+
+```ts
+database({ orgs, posts });                                 // memoryDriver() — the default
+database({ orgs, posts }, { driver: postgresDriver() });   // production
+```
+
+| | `memoryDriver()` | `postgresDriver()` |
+|---|---|---|
+| Rows live | in a `Map` | in Postgres |
+| For | tests, `x dev` before the first migration | production |
+| Transaction | `memoryTransactor()` — undo closures | `postgresTransactor()` — real `BEGIN`/`COMMIT` |
+
+They are not two implementations of an idea. They share the plan (scope, sort order, page size),
+the cursor codec and the `Repo<T>` contract, so a page taken in a test means the same thing as a
+page taken in production. `postgresDriver()` takes no connection: `db()` from `@ultimat3/db`
+returns the open transaction when there is one, so a repository call inside `withTransaction`
+joins it without being told — which is how a job's outbox row lands atomically with the write
+that enqueued it.
+
+Every value is bound to `$n` and every identifier is resolved through the entity, so a column
+name can only be one the entity declared and a row value can never become SQL.
 
 ## Tenancy is a guard
 
-An entity with an `orgId` column can only be queried through a plan carrying an org
-predicate. Without one: `X_TENANCY_UNSCOPED`, at the seam, every time.
+`tenant: 'orgId'` on the entity names the column outright. Omit it and it is inferred — a
+`.tenant()` column, else one named `orgId` — so an entity never becomes unscoped by forgetting the
+key; name a column that does not exist and the declaration fails with `X_INVARIANT_VIOLATED`.
+
+Either way, every read then needs an org predicate. Without one: `X_TENANCY_UNSCOPED`, at the
+seam, every time. Writes are reads: `update(id, patch)` and `delete(id)` build the same plan, so
+an id alone never addresses a row, and another tenant's id is `X_NOT_FOUND` rather than theirs.
+
+## Seeds
+
+`defineSeed('dev', async ({ insert, id }) => …)`. `id('post:tenancy')` is a UUID v5 of the label,
+so the same fixture graph gets the same ids on every machine. Rows go through the columns and
+the invariants, which makes a seed a test of the schema as well.
 
 ## Errors
 
@@ -63,7 +147,9 @@ predicate. Without one: `X_TENANCY_UNSCOPED`, at the seam, every time.
 
 ## Boundaries
 
-Tier 2. Imports `@ultimat3/core` and `@ultimat3/schema` only. There is deliberately no
-`drizzle-orm` dependency: `ColumnDef`/`TableDef` are the narrow structural types this
-package consumes, so generated SQL stays readable and an agent can self-correct
-against it. `@ultimat3/cache` invalidates by the `entity:<name>` tag string.
+Tier 2. Imports `@ultimat3/core`, `@ultimat3/schema` and `@ultimat3/db` only — `db` is tier 1
+(it imports `core` and nothing else), which is what keeps `Driver` and its production
+implementation in one package instead of two. No `drizzle-orm` dependency:
+`types.ts` declares the narrow structural column vocabulary this package consumes, so the
+generated SQL stays readable and an agent can self-correct against it. `@ultimat3/cache`
+invalidates by the `entity:<name>` tag.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ultimat3/entity",
-  "version": "0.0.1",
+  "version": "1.0.0",
   "description": "A table + its domain type + invariants the database also enforces",
   "license": "MIT",
   "type": "module",
@@ -30,7 +30,8 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@ultimat3/core": "^0.0.1",
-    "@ultimat3/schema": "^0.0.1"
+    "@ultimat3/core": "1.0.0",
+    "@ultimat3/db": "1.0.0",
+    "@ultimat3/schema": "1.0.0"
   }
 }

package/src/column.d.ts

@@ -0,0 +1,28 @@
+import type { AnyColumn, Column, ColumnDefault, ColumnMeta, TimestampColumn } from './types';
+export declare const snake: (value: string) => string;
+export declare const GENERATED_UUID: ColumnDefault;
+export declare const GENERATED_NOW: ColumnDefault;
+/** Every column starts here: not null, no key, no index. */
+export declare const BARE: Omit<ColumnMeta, 'kind'>;
+export interface Binding {
+    readonly table: string;
+    /** camelCase key on the row. */
+    readonly property: string;
+    /** snake_case physical column name. */
+    readonly name: string;
+}
+/**
+ * Called once per column by `entity()`. A column object belongs to exactly one table: sharing
+ * one between two entities would give it two physical names and silently mis-name a foreign
+ * key, so a second binding is a declaration-time error.
+ */
+export declare const bindColumn: (column: AnyColumn, table: string, property: string) => Binding;
+export declare const bindingOf: (column: AnyColumn) => Binding | undefined;
+export declare const makeColumn: <T, Optional extends boolean>(meta: ColumnMeta, parse: (value: unknown) => T, optional: Optional) => Column<T, Optional>;
+export declare const column: <T>(kind: ColumnMeta['kind'], parse: (value: unknown) => T, extra?: Partial<ColumnMeta>) => Column<T>;
+/**
+ * `timestamptz`, always. There is no naive-timestamp builder and there will not be one: a
+ * `timestamp without time zone` is a bug that only surfaces twice a year.
+ */
+export declare const makeTimestamp: <Optional extends boolean>(meta: ColumnMeta, parse: (value: unknown) => Date, optional: Optional) => TimestampColumn<Optional>;
+//# sourceMappingURL=column.d.ts.map

package/src/column.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"column.d.ts","sourceRoot":"","sources":["column.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,EAAE,UAAU,EAAE,eAAe,EAAE,MAAM,SAAS,CAAC;AAE7F,eAAO,MAAM,KAAK,UAAW,MAAM,KAAG,MACsB,CAAC;AAE7D,eAAO,MAAM,cAAc,EAAE,aAAoD,CAAC;AAClF,eAAO,MAAM,aAAa,EAAE,aAAgD,CAAC;AAE7E,4DAA4D;AAC5D,eAAO,MAAM,IAAI,EAAE,IAAI,CAAC,UAAU,EAAE,MAAM,CAMzC,CAAC;AAEF,MAAM,WAAW,OAAO;IACtB,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,gCAAgC;IAChC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,uCAAuC;IACvC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB;AAID;;;;GAIG;AACH,eAAO,MAAM,UAAU,WAAY,SAAS,SAAS,MAAM,YAAY,MAAM,KAAG,OAa/E,CAAC;AAEF,eAAO,MAAM,SAAS,WAAY,SAAS,KAAG,OAAO,GAAG,SAAiC,CAAC;AAc1F,eAAO,MAAM,UAAU,GAAI,CAAC,EAAE,QAAQ,SAAS,OAAO,QAC9C,UAAU,SACT,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,YAClB,QAAQ,KACjB,MAAM,CAAC,CAAC,EAAE,QAAQ,CAuCnB,CAAC;AAEH,eAAO,MAAM,MAAM,GAAI,CAAC,QAChB,UAAU,CAAC,MAAM,CAAC,SACjB,CAAC,KAAK,EAAE,OAAO,KAAK,CAAC,UACrB,OAAO,CAAC,UAAU,CAAC,KACzB,MAAM,CAAC,CAAC,CAAoE,CAAC;AAEhF;;;GAGG;AACH,eAAO,MAAM,aAAa,GAAI,QAAQ,SAAS,OAAO,QAC9C,UAAU,SACT,CAAC,KAAK,EAAE,OAAO,KAAK,IAAI,YACrB,QAAQ,KACjB,eAAe,CAAC,QAAQ,CAIzB,CAAC"}

package/src/column.js

@@ -0,0 +1,75 @@
+// The chain every column builder is made of. Each link returns a new column, so a chain reads
+// in declaration order and a builder is never mutated behind someone's back.
+//
+// Where a column landed (table, property key, physical name) is recorded in a binding rather
+// than on the column: the author writes the property key once, `entity()` derives `orgId` ->
+// `org_id` from it, and a lazy `.references(() => orgs.id)` can still resolve the target's
+// physical name even though two schema modules import each other in a cycle.
+import { invariantViolated } from './errors';
+export const snake = (value) => value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+export const GENERATED_UUID = { kind: 'generated', by: 'uuid-v7' };
+export const GENERATED_NOW = { kind: 'generated', by: 'now' };
+/** Every column starts here: not null, no key, no index. */
+export const BARE = {
+    notNull: true,
+    primaryKey: false,
+    unique: false,
+    index: false,
+    tenant: false,
+};
+const bindings = new WeakMap();
+/**
+ * Called once per column by `entity()`. A column object belongs to exactly one table: sharing
+ * one between two entities would give it two physical names and silently mis-name a foreign
+ * key, so a second binding is a declaration-time error.
+ */
+export const bindColumn = (column, table, property) => {
+    const existing = bindings.get(column);
+    if (existing !== undefined && existing.table !== table) {
+        throw invariantViolated(table, property, `this column is already bound to ${existing.table}.${existing.name}; ` +
+            'build a new column instead of sharing one between entities');
+    }
+    const binding = { table, property, name: snake(property) };
+    bindings.set(column, binding);
+    return binding;
+};
+export const bindingOf = (column) => bindings.get(column);
+const literal = (value) => {
+    if (value === null)
+        return { kind: 'value', value: null };
+    if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+        return { kind: 'value', value };
+    }
+    throw invariantViolated('column', 'default', `a default must be a literal; got ${typeof value}. For an instant use timestamp().defaultNow()`);
+};
+export const makeColumn = (meta, parse, optional) => ({
+    $meta: meta,
+    $parse: parse,
+    $optional: optional,
+    primaryKey: () => {
+        // Only a uuid key can be generated for the caller; any other key must be supplied.
+        const generated = meta.kind === 'uuid' && meta.default === undefined;
+        return makeColumn({ ...meta, primaryKey: true, ...(generated ? { default: GENERATED_UUID } : {}) }, parse, generated || meta.default !== undefined);
+    },
+    nullable: () => makeColumn({ ...meta, notNull: false }, (value) => (value === null || value === undefined ? null : parse(value)), optional),
+    unique: () => makeColumn({ ...meta, unique: true }, parse, optional),
+    tenant: () => makeColumn({ ...meta, tenant: true, index: true }, parse, optional),
+    references: (target, options = {}) => makeColumn({
+        ...meta,
+        references: target,
+        index: true,
+        ...(options.onDelete === undefined ? {} : { onDelete: options.onDelete }),
+    }, parse, optional),
+    default: (value) => makeColumn({ ...meta, default: literal(value) }, parse, true),
+});
+export const column = (kind, parse, extra = {}) => makeColumn({ ...BARE, ...extra, kind }, parse, false);
+/**
+ * `timestamptz`, always. There is no naive-timestamp builder and there will not be one: a
+ * `timestamp without time zone` is a bug that only surfaces twice a year.
+ */
+export const makeTimestamp = (meta, parse, optional) => ({
+    ...makeColumn(meta, parse, optional),
+    defaultNow: () => makeTimestamp({ ...meta, default: GENERATED_NOW }, parse, true),
+    onUpdateNow: () => makeTimestamp({ ...meta, onUpdate: GENERATED_NOW }, parse, optional),
+});
+//# sourceMappingURL=column.js.map

package/src/column.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"column.js","sourceRoot":"","sources":["column.ts"],"names":[],"mappings":"AAAA,8FAA8F;AAC9F,6EAA6E;AAC7E,EAAE;AACF,6FAA6F;AAC7F,6FAA6F;AAC7F,2FAA2F;AAC3F,6EAA6E;AAE7E,OAAO,EAAE,iBAAiB,EAAE,MAAM,UAAU,CAAC;AAG7C,MAAM,CAAC,MAAM,KAAK,GAAG,CAAC,KAAa,EAAU,EAAE,CAC7C,KAAK,CAAC,OAAO,CAAC,oBAAoB,EAAE,OAAO,CAAC,CAAC,WAAW,EAAE,CAAC;AAE7D,MAAM,CAAC,MAAM,cAAc,GAAkB,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,SAAS,EAAE,CAAC;AAClF,MAAM,CAAC,MAAM,aAAa,GAAkB,EAAE,IAAI,EAAE,WAAW,EAAE,EAAE,EAAE,KAAK,EAAE,CAAC;AAE7E,4DAA4D;AAC5D,MAAM,CAAC,MAAM,IAAI,GAA6B;IAC5C,OAAO,EAAE,IAAI;IACb,UAAU,EAAE,KAAK;IACjB,MAAM,EAAE,KAAK;IACb,KAAK,EAAE,KAAK;IACZ,MAAM,EAAE,KAAK;CACd,CAAC;AAUF,MAAM,QAAQ,GAAG,IAAI,OAAO,EAAsB,CAAC;AAEnD;;;;GAIG;AACH,MAAM,CAAC,MAAM,UAAU,GAAG,CAAC,MAAiB,EAAE,KAAa,EAAE,QAAgB,EAAW,EAAE;IACxF,MAAM,QAAQ,GAAG,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;IACtC,IAAI,QAAQ,KAAK,SAAS,IAAI,QAAQ,CAAC,KAAK,KAAK,KAAK,EAAE,CAAC;QACvD,MAAM,iBAAiB,CACrB,KAAK,EACL,QAAQ,EACR,mCAAmC,QAAQ,CAAC,KAAK,IAAI,QAAQ,CAAC,IAAI,IAAI;YACpE,4DAA4D,CAC/D,CAAC;IACJ,CAAC;IACD,MAAM,OAAO,GAAY,EAAE,KAAK,EAAE,QAAQ,EAAE,IAAI,EAAE,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC;IACpE,QAAQ,CAAC,GAAG,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAC9B,OAAO,OAAO,CAAC;AACjB,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,SAAS,GAAG,CAAC,MAAiB,EAAuB,EAAE,CAAC,QAAQ,CAAC,GAAG,CAAC,MAAM,CAAC,CAAC;AAE1F,MAAM,OAAO,GAAG,CAAC,KAAc,EAAiB,EAAE;IAChD,IAAI,KAAK,KAAK,IAAI;QAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,IAAI,EAAE,CAAC;IAC1D,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,QAAQ,IAAI,OAAO,KAAK,KAAK,SAAS,EAAE,CAAC;QACzF,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,CAAC;IAClC,CAAC;IACD,MAAM,iBAAiB,CACrB,QAAQ,EACR,SAAS,EACT,oCAAoC,OAAO,KAAK,+CAA+C,CAChG,CAAC;AACJ,CAAC,CAAC;AAEF,MAAM,CAAC,MAAM,UAAU,GAAG,CACxB,IAAgB,EAChB,KAA4B,EAC5B,QAAkB,EACG,EAAE,CAAC,CAAC;IACzB,KAAK,EAAE,IAAI;IACX,MAAM,EAAE,KAAK;IACb,SAAS,EAAE,QAAQ;IAEnB,UAAU,EAAE,GAAG,EAAE;QACf,mFAAmF;QACnF,MAAM,SAAS,GAAG,IAAI,CAAC,IAAI,KAAK,MAAM,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,CAAC;QACrE,OAAO,UAAU,CACf,EAAE,GAAG,IAAI,EAAE,UAAU,EAAE,IAAI,EAAE,GAAG,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,cAAc,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC,EAAE,EAChF,KAAK,EACL,SAAS,IAAI,IAAI,CAAC,OAAO,KAAK,SAAS,CACxC,CAAC;IACJ,CAAC;IAED,QAAQ,EAAE,GAAG,EAAE,CACb,UAAU,CACR,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,EAAE,EAC3B,CAAC,KAAK,EAAE,EAAE,CAAC,CAAC,KAAK,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,CAAC,CAAC,CAAC,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,CAAC,CAAC,EACxE,QAAQ,CACT;IAEH,MAAM,EAAE,GAAG,EAAE,CAAC,UAAU,CAAc,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC;IAEjF,MAAM,EAAE,GAAG,EAAE,CAAC,UAAU,CAAc,EAAE,GAAG,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC;IAE9F,UAAU,EAAE,CAAC,MAAM,EAAE,OAAO,GAAG,EAAE,EAAE,EAAE,CACnC,UAAU,CACR;QACE,GAAG,IAAI;QACP,UAAU,EAAE,MAAM;QAClB,KAAK,EAAE,IAAI;QACX,GAAG,CAAC,OAAO,CAAC,QAAQ,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,QAAQ,EAAE,OAAO,CAAC,QAAQ,EAAE,CAAC;KAC1E,EACD,KAAK,EACL,QAAQ,CACT;IAEH,OAAO,EAAE,CAAC,KAAK,EAAE,EAAE,CAAC,UAAU,CAAU,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,OAAO,CAAC,KAAK,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC;CAC3F,CAAC,CAAC;AAEH,MAAM,CAAC,MAAM,MAAM,GAAG,CACpB,IAAwB,EACxB,KAA4B,EAC5B,KAAK,GAAwB,EAAE,EACpB,EAAE,CAAC,UAAU,CAAW,EAAE,GAAG,IAAI,EAAE,GAAG,KAAK,EAAE,IAAI,EAAE,EAAE,KAAK,EAAE,KAAK,CAAC,CAAC;AAEhF;;;GAGG;AACH,MAAM,CAAC,MAAM,aAAa,GAAG,CAC3B,IAAgB,EAChB,KAA+B,EAC/B,QAAkB,EACS,EAAE,CAAC,CAAC;IAC/B,GAAG,UAAU,CAAiB,IAAI,EAAE,KAAK,EAAE,QAAQ,CAAC;IACpD,UAAU,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,EAAE,GAAG,IAAI,EAAE,OAAO,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC;IACjF,WAAW,EAAE,GAAG,EAAE,CAAC,aAAa,CAAC,EAAE,GAAG,IAAI,EAAE,QAAQ,EAAE,aAAa,EAAE,EAAE,KAAK,EAAE,QAAQ,CAAC;CACxF,CAAC,CAAC"}

package/src/column.ts

@@ -0,0 +1,134 @@
+// The chain every column builder is made of. Each link returns a new column, so a chain reads
+// in declaration order and a builder is never mutated behind someone's back.
+//
+// Where a column landed (table, property key, physical name) is recorded in a binding rather
+// than on the column: the author writes the property key once, `entity()` derives `orgId` ->
+// `org_id` from it, and a lazy `.references(() => orgs.id)` can still resolve the target's
+// physical name even though two schema modules import each other in a cycle.
+
+import { invariantViolated } from './errors';
+import type { AnyColumn, Column, ColumnDefault, ColumnMeta, TimestampColumn } from './types';
+
+export const snake = (value: string): string =>
+  value.replace(/([a-z0-9])([A-Z])/g, '$1_$2').toLowerCase();
+
+export const GENERATED_UUID: ColumnDefault = { kind: 'generated', by: 'uuid-v7' };
+export const GENERATED_NOW: ColumnDefault = { kind: 'generated', by: 'now' };
+
+/** Every column starts here: not null, no key, no index. */
+export const BARE: Omit<ColumnMeta, 'kind'> = {
+  notNull: true,
+  primaryKey: false,
+  unique: false,
+  index: false,
+  tenant: false,
+};
+
+export interface Binding {
+  readonly table: string;
+  /** camelCase key on the row. */
+  readonly property: string;
+  /** snake_case physical column name. */
+  readonly name: string;
+}
+
+const bindings = new WeakMap<AnyColumn, Binding>();
+
+/**
+ * Called once per column by `entity()`. A column object belongs to exactly one table: sharing
+ * one between two entities would give it two physical names and silently mis-name a foreign
+ * key, so a second binding is a declaration-time error.
+ */
+export const bindColumn = (column: AnyColumn, table: string, property: string): Binding => {
+  const existing = bindings.get(column);
+  if (existing !== undefined && existing.table !== table) {
+    throw invariantViolated(
+      table,
+      property,
+      `this column is already bound to ${existing.table}.${existing.name}; ` +
+        'build a new column instead of sharing one between entities',
+    );
+  }
+  const binding: Binding = { table, property, name: snake(property) };
+  bindings.set(column, binding);
+  return binding;
+};
+
+export const bindingOf = (column: AnyColumn): Binding | undefined => bindings.get(column);
+
+const literal = (value: unknown): ColumnDefault => {
+  if (value === null) return { kind: 'value', value: null };
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return { kind: 'value', value };
+  }
+  throw invariantViolated(
+    'column',
+    'default',
+    `a default must be a literal; got ${typeof value}. For an instant use timestamp().defaultNow()`,
+  );
+};
+
+export const makeColumn = <T, Optional extends boolean>(
+  meta: ColumnMeta,
+  parse: (value: unknown) => T,
+  optional: Optional,
+): Column<T, Optional> => ({
+  $meta: meta,
+  $parse: parse,
+  $optional: optional,
+
+  primaryKey: () => {
+    // Only a uuid key can be generated for the caller; any other key must be supplied.
+    const generated = meta.kind === 'uuid' && meta.default === undefined;
+    return makeColumn<T, boolean>(
+      { ...meta, primaryKey: true, ...(generated ? { default: GENERATED_UUID } : {}) },
+      parse,
+      generated || meta.default !== undefined,
+    );
+  },
+
+  nullable: () =>
+    makeColumn<T | null, Optional>(
+      { ...meta, notNull: false },
+      (value) => (value === null || value === undefined ? null : parse(value)),
+      optional,
+    ),
+
+  unique: () => makeColumn<T, Optional>({ ...meta, unique: true }, parse, optional),
+
+  tenant: () => makeColumn<T, Optional>({ ...meta, tenant: true, index: true }, parse, optional),
+
+  references: (target, options = {}) =>
+    makeColumn<T, Optional>(
+      {
+        ...meta,
+        references: target,
+        index: true,
+        ...(options.onDelete === undefined ? {} : { onDelete: options.onDelete }),
+      },
+      parse,
+      optional,
+    ),
+
+  default: (value) => makeColumn<T, true>({ ...meta, default: literal(value) }, parse, true),
+});
+
+export const column = <T>(
+  kind: ColumnMeta['kind'],
+  parse: (value: unknown) => T,
+  extra: Partial<ColumnMeta> = {},
+): Column<T> => makeColumn<T, false>({ ...BARE, ...extra, kind }, parse, false);
+
+/**
+ * `timestamptz`, always. There is no naive-timestamp builder and there will not be one: a
+ * `timestamp without time zone` is a bug that only surfaces twice a year.
+ */
+export const makeTimestamp = <Optional extends boolean>(
+  meta: ColumnMeta,
+  parse: (value: unknown) => Date,
+  optional: Optional,
+): TimestampColumn<Optional> => ({
+  ...makeColumn<Date, Optional>(meta, parse, optional),
+  defaultNow: () => makeTimestamp({ ...meta, default: GENERATED_NOW }, parse, true),
+  onUpdateNow: () => makeTimestamp({ ...meta, onUpdate: GENERATED_NOW }, parse, optional),
+});

package/src/columns.d.ts

@@ -0,0 +1,39 @@
+import type { Column, MoneyValue, TimestampColumn, UuidColumn } from './types';
+/** uuid v7: time-ordered, so a primary key index stays append-friendly. */
+export declare const newId: () => string;
+export declare const uuid: () => UuidColumn;
+export interface TextOptions {
+    /** Emits `char_length(<column>) <= max`, so Postgres refuses an over-long string too. */
+    readonly max?: number;
+}
+export declare const text: (options?: TextOptions) => Column<string>;
+export declare const integer: () => Column<number>;
+export declare const boolean: () => Column<boolean>;
+/** Always `timestamptz`. UTC storage is not a per-table decision. */
+export declare const timestamp: () => TimestampColumn;
+/**
+ * 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 declare const enumerated: <const V extends readonly string[]>(values: V) => Column<V[number]>;
+/**
+ * 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 declare const url: () => Column<string>;
+/**
+ * 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 declare const tz: <const Z extends readonly string[]>(zones: Z) => Column<Z[number]>;
+export declare const locale: <const L extends readonly string[]>(locales: L) => Column<L[number]>;
+/**
+ * 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 declare const money: () => Column<MoneyValue>;
+/** The CHECK that stops a psql session writing a currency the app would refuse. */
+export declare const currencyCheck: (currencyColumn: string) => string;
+//# sourceMappingURL=columns.d.ts.map

package/src/columns.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"columns.d.ts","sourceRoot":"","sources":["columns.ts"],"names":[],"mappings":"AAOA,OAAO,KAAK,EAAE,MAAM,EAAc,UAAU,EAAE,eAAe,EAAE,UAAU,EAAE,MAAM,SAAS,CAAC;AAM3F,2EAA2E;AAC3E,eAAO,MAAM,KAAK,QAAO,MAAkB,CAAC;AAS5C,eAAO,MAAM,IAAI,QAAO,UAUtB,CAAC;AAEH,MAAM,WAAW,WAAW;IAC1B,yFAAyF;IACzF,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,CAAC;CACvB;AAED,eAAO,MAAM,IAAI,aAAa,WAAW,KAAQ,MAAM,CAAC,MAAM,CAQ3D,CAAC;AAEJ,eAAO,MAAM,OAAO,QAAO,MAAM,CAAC,MAAM,CAKrC,CAAC;AAEJ,eAAO,MAAM,OAAO,QAAO,MAAM,CAAC,OAAO,CAGtC,CAAC;AAWJ,qEAAqE;AACrE,eAAO,MAAM,SAAS,QAAO,eACgD,CAAC;AAS9E;;;;GAIG;AACH,eAAO,MAAM,UAAU,GAAI,KAAK,CAAC,CAAC,SAAS,SAAS,MAAM,EAAE,UAAU,CAAC,KAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAUzF,CAAC;AAEF;;;GAGG;AACH,eAAO,MAAM,GAAG,QAAO,MAAM,CAAC,MAAM,CAejC,CAAC;AAWJ;;;GAGG;AACH,eAAO,MAAM,EAAE,GAAI,KAAK,CAAC,CAAC,SAAS,SAAS,MAAM,EAAE,SAAS,CAAC,KAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAahF,CAAC;AAIF,eAAO,MAAM,MAAM,GAAI,KAAK,CAAC,CAAC,SAAS,SAAS,MAAM,EAAE,WAAW,CAAC,KAAG,MAAM,CAAC,CAAC,CAAC,MAAM,CAAC,CAatF,CAAC;AA8BF;;;;GAIG;AACH,eAAO,MAAM,KAAK,QAAO,MAAM,CAAC,UAAU,CAA4C,CAAC;AAEvF,mFAAmF;AACnF,eAAO,MAAM,aAAa,mBAAoB,MAAM,KAAG,MAA4C,CAAC"}