@ultimat3/entity 0.0.1 → 1.1.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.1.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.1.0",
+    "@ultimat3/db": "1.1.0",
+    "@ultimat3/schema": "1.1.0"
   }
 }

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),
+});