@ultimat3/entity 0.0.1 → 1.1.0

package/src/tenancy.ts

@@ -1,8 +1,9 @@
-// Multi-tenancy is a guard, not a convention. An entity with an `orgId` column can
-// only be queried through a plan that carries an org predicate; building one without
-// it throws `X_TENANCY_UNSCOPED` at the seam instead of leaking another tenant's rows.
-import { tenancyUnscoped } from './errors';
-import type { TableDef } from './types';
+// Multi-tenancy is a guard, not a convention. An entity with a tenant column can only be read
+// through a plan that carries an org predicate; building one without it throws
+// `X_TENANCY_UNSCOPED` at the seam instead of leaking another tenant's rows.
+
+import { EntityError, tenancyUnscoped } from './errors';
+import type { ColumnMap } from './types';
 
 export type Operator =
   | 'eq'
@@ -24,18 +25,62 @@ export interface Predicate {
 
 export type SortDirection = 'asc' | 'desc';
 
+export interface SortKey {
+  readonly column: string;
+  readonly direction: SortDirection;
+}
+
 export interface QueryPlan {
   readonly entity: string;
   readonly where: readonly Predicate[];
-  readonly orderBy: readonly { readonly column: string; readonly direction: SortDirection }[];
+  readonly orderBy: readonly SortKey[];
   readonly limit: number;
+  /** Keyset position. There is no `offset` and there will not be one — see `repo.ts`. */
   readonly cursor?: string;
+  readonly select?: readonly string[];
 }
 
+/** The property key a tenant column takes when it is not marked explicitly. */
 export const ORG_COLUMN = 'orgId';
 
-/** True when the table declares an `orgId` column — presence is the switch. */
-export const isOrgScoped = (table: TableDef): boolean => Object.hasOwn(table.columns, ORG_COLUMN);
+/**
+ * `.tenant()` is the switch; a column literally named `orgId` counts too, so an entity cannot
+ * become unscoped by forgetting one call.
+ */
+export const tenantColumnOf = (columns: ColumnMap): string | null => {
+  for (const [property, column] of Object.entries(columns)) {
+    if (column.$meta.tenant) return property;
+  }
+  return Object.hasOwn(columns, ORG_COLUMN) ? ORG_COLUMN : null;
+};
+
+export const isOrgScoped = (columns: ColumnMap): boolean => tenantColumnOf(columns) !== null;
+
+/**
+ * `entity(name, { tenant: 'workspaceId' })` wins over inference — a tenant column need not be
+ * called `orgId` and need not carry `.tenant()`. Omitting it keeps the inference, so an entity
+ * cannot become unscoped by forgetting the key; naming a column that does not exist is a
+ * declaration error, because the alternative is a silently unscoped table.
+ */
+export const resolveTenantColumn = (
+  entityName: string,
+  columns: ColumnMap,
+  declared: string | undefined,
+): string | null => {
+  if (declared === undefined) return tenantColumnOf(columns);
+  if (!Object.hasOwn(columns, declared)) {
+    const available = Object.keys(columns).join(', ');
+    // Not `invariantViolated`: its fix points at `x entity explain`, which describes invariants
+    // the author never wrote. What repairs this is one edit to the declaration, so the error
+    // carries that edit and both ways out of it.
+    throw new EntityError({
+      code: 'X_INVARIANT_VIOLATED',
+      cause: `${entityName}.tenant: tenant: '${declared}' names no column — pick from: ${available}`,
+      fix: `set tenant to one of ${available} in entity('${entityName}'), or remove the tenant key — inference then takes the .tenant() column, else one named ${ORG_COLUMN}`,
+    });
+  }
+  return declared;
+};
 
 export const emptyPlan = (entity: string, limit = 50): QueryPlan => ({
   entity,
@@ -44,31 +89,35 @@ export const emptyPlan = (entity: string, limit = 50): QueryPlan => ({
   limit,
 });
 
-export const hasOrgPredicate = (plan: QueryPlan): boolean =>
-  plan.where.some((predicate) => predicate.column === ORG_COLUMN);
+export const hasOrgPredicate = (plan: QueryPlan, column: string = ORG_COLUMN): boolean =>
+  plan.where.some((predicate) => predicate.column === column);
 
 /** Adds the org predicate exactly once; calling it twice is not an error. */
-export const orgScoped = (plan: QueryPlan, orgId: string): QueryPlan =>
-  hasOrgPredicate(plan)
+export const orgScoped = (
+  plan: QueryPlan,
+  orgId: string,
+  column: string = ORG_COLUMN,
+): QueryPlan =>
+  hasOrgPredicate(plan, column)
     ? plan
-    : { ...plan, where: [...plan.where, { column: ORG_COLUMN, op: 'eq', value: orgId }] };
+    : { ...plan, where: [...plan.where, { column, op: 'eq', value: orgId }] };
 
 /**
- * Called by every repository operation. Runtime here, and a build-time check in
- * `x verify` that no query for a tenant-scoped entity is constructed without it.
+ * Called by every repository operation. Runtime here, and a build-time check in `x verify`
+ * that no query for a tenant-scoped entity is constructed without it.
  */
 export const assertScoped = (
   entityName: string,
-  table: TableDef,
+  tenantColumn: string | null,
   operation: string,
   plan: QueryPlan,
 ): void => {
-  if (!isOrgScoped(table)) return;
-  if (hasOrgPredicate(plan)) return;
+  if (tenantColumn === null) return;
+  if (hasOrgPredicate(plan, tenantColumn)) return;
   throw tenancyUnscoped(entityName, operation);
 };
 
-/** Debug/`x db explain` rendering. Values stay out: a plan is safe to log. */
+/** Debug and `x db explain` rendering. Values stay out: a plan is safe to log. */
 export const describePlan = (plan: QueryPlan): string => {
   const where = plan.where
     .map((predicate) => `${predicate.column} ${predicate.op} ?`)

package/src/types.ts

@@ -1,9 +1,12 @@
-// The narrow structural types this package consumes. Drizzle is the production
-// backing for `TableDef`/`ColumnDef` (see README), but declaring the shape we use
-// instead of depending on the ORM keeps the generated SQL readable and keeps this
-// package free of a dependency an agent would have to learn to read.
+// The structural vocabulary of a column. The physical layer is this package's own hand-written
+// `postgresDriver()` (`pg-driver.ts` / `pg-sql.ts`), not an ORM; declaring the narrow shape we
+// consume keeps the emitted SQL readable and keeps this package free of a dependency an agent
+// must learn to read.
+//
+// A column carries its TypeScript type in `$parse`, which is what lets the row type be derived
+// from the column set instead of being written a second time as a hand-maintained schema.
 
-/** Postgres types the blessed column helpers emit. No `float` for money, ever. */
+/** Postgres types the blessed builders emit. `money` expands to `bigint` + `char(3)`. */
 export type ColumnKind =
   | 'uuid'
   | 'text'
@@ -11,67 +14,114 @@ export type ColumnKind =
   | 'boolean'
   | 'integer'
   | 'bigint'
-  | 'numeric'
   | 'timestamptz'
-  | 'date'
-  | 'jsonb';
+  | 'jsonb'
+  | 'money';
 
 export type ColumnDefault =
-  | { readonly kind: 'sql'; readonly expression: string }
   | { readonly kind: 'value'; readonly value: string | number | boolean | null }
   | { readonly kind: 'generated'; readonly by: 'uuid-v7' | 'now' };
 
-export interface ReferenceDef {
-  readonly table: string;
-  readonly column: string;
-  readonly onDelete?: 'cascade' | 'restrict' | 'set null';
+export type OnDelete = 'cascade' | 'restrict' | 'set null';
+
+export interface ReferenceOptions {
+  readonly onDelete?: OnDelete;
 }
 
-export interface ColumnDef<T> {
-  /** snake_case physical name; the property key is the camelCase domain name. */
-  readonly name: string;
+/** The single value a money column puts on the row. Two physical columns back it. */
+export interface MoneyValue {
+  readonly minor: bigint;
+  readonly currency: string;
+}
+
+/** What a writer may hand a money column. An integer `number` widens; a float throws. */
+export interface MoneyInput {
+  readonly minor: bigint | number;
+  readonly currency: string;
+}
+
+/**
+ * What the author declared. Where it landed — table, property key, physical name — is the
+ * binding `entity()` records (see `column.ts`), so a name is never written twice.
+ */
+export interface ColumnMeta {
   readonly kind: ColumnKind;
   readonly notNull: boolean;
   readonly primaryKey: boolean;
   readonly unique: boolean;
+  readonly index: boolean;
+  /** Presence of a tenant column is what turns tenancy on. See `tenancy.ts`. */
+  readonly tenant: boolean;
   readonly length?: number;
+  readonly values?: readonly string[];
   readonly default?: ColumnDefault;
-  /** SQL expression emitted as a CHECK next to the column. */
-  readonly check?: string;
-  readonly references?: ReferenceDef;
-  readonly index: boolean;
-  readonly comment?: string;
-  /**
-   * Runtime guard AND the carrier of the column's TypeScript type. Every write goes
-   * through it, which is how `money()` can refuse a float instead of rounding it.
-   */
-  readonly parse: (value: unknown) => T;
+  readonly onUpdate?: ColumnDefault;
+  /** Takes the physical name, so a CHECK can be written before that name is known. */
+  readonly check?: (column: string) => string;
+  /** A thunk: schema modules reference each other in a cycle. */
+  readonly references?: () => AnyColumn;
+  readonly onDelete?: OnDelete;
 }
 
-export type ColumnMap = Readonly<Record<string, ColumnDef<unknown>>>;
+/**
+ * `Optional` is the phantom that says "this column has a default", so an insert may omit it.
+ * It is a real boolean at runtime too, so nothing has to be re-derived to check it.
+ */
+export interface Column<T, Optional extends boolean = false> {
+  readonly $meta: ColumnMeta;
+  /** Runtime guard AND the carrier of the column's TypeScript type. */
+  readonly $parse: (value: unknown) => T;
+  readonly $optional: Optional;
+  /** `boolean`: only a uuid key carries a generated default, so only it becomes optional. */
+  primaryKey(): Column<T, boolean>;
+  nullable(): Column<T | null, Optional>;
+  unique(): Column<T, Optional>;
+  /** Marks the tenant column; a query without an org predicate then throws. */
+  tenant(): Column<T, Optional>;
+  references(target: () => AnyColumn, options?: ReferenceOptions): Column<T, Optional>;
+  default(value: T): Column<T, true>;
+}
 
-export interface IndexDef {
-  readonly name: string;
-  readonly columns: readonly string[];
-  readonly unique: boolean;
-  /** Partial index predicate — soft-deleted rows are excluded with this. */
-  readonly where?: string;
+/** A uuid primary key is generated (v7) when omitted, which is why it narrows to `true`. */
+export interface UuidColumn<Optional extends boolean = false> extends Column<string, Optional> {
+  primaryKey(): Column<string, true>;
 }
 
-export interface TableDef<C extends ColumnMap = ColumnMap> {
-  readonly name: string;
-  readonly columns: C;
-  readonly primaryKey: readonly string[];
-  readonly indexes: readonly IndexDef[];
+export interface TimestampColumn<Optional extends boolean = false> extends Column<Date, Optional> {
+  defaultNow(): TimestampColumn<true>;
+  onUpdateNow(): TimestampColumn<Optional>;
 }
 
-/** The row type a table describes, derived from its columns' parse signatures. */
+export type AnyColumn = Column<unknown, boolean>;
+
+export type ColumnMap = Readonly<Record<string, AnyColumn>>;
+
+export type TypeOf<C> = C extends Column<infer T, boolean> ? T : never;
+
+/** The row type a column set describes. This derivation is why the package exists. */
 export type RowOf<C extends ColumnMap> = {
-  readonly [K in keyof C]: C[K] extends ColumnDef<infer T> ? T : never;
+  readonly [K in keyof C]: TypeOf<C[K]>;
 };
 
-export const columnNames = (table: TableDef): readonly string[] =>
-  Object.values(table.columns).map((column) => column.name);
+type DefaultedKeys<C extends ColumnMap> = {
+  [K in keyof C]-?: C[K]['$optional'] extends true ? K : never;
+}[keyof C];
+
+/** Money is the one column whose write shape is wider than its row shape. */
+type InputOf<T> = T extends MoneyValue ? MoneyInput : T;
+
+/** What an insert must supply: every column except the ones carrying a default. */
+export type Insertable<C extends ColumnMap> = {
+  readonly [K in Exclude<keyof C, DefaultedKeys<C>>]: InputOf<TypeOf<C[K]>>;
+} & {
+  readonly [K in DefaultedKeys<C>]?: InputOf<TypeOf<C[K]>>;
+};
 
-export const hasColumn = (table: TableDef, property: string): boolean =>
-  Object.hasOwn(table.columns, property);
+export interface IndexDef {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly unique: boolean;
+  readonly order?: 'asc' | 'desc';
+  /** Partial index predicate — a soft-deleted row is excluded with this. */
+  readonly where?: string;
+}

package/src/view.ts

@@ -0,0 +1,97 @@
+// `posts.$view(['id', 'title'])` — the hop between an entity and an action's `output`: a Standard
+// Schema over a subset of the row, so `output: PostView` never re-declares a shape the columns
+// already describe. Values are validated by the entity's own column parsers; an unknown key is a
+// declaration-time failure, not a surprise on the first request.
+
+import type { StandardSchemaV1 } from '@ultimat3/schema';
+import { invariantViolated } from './errors';
+import type { AnyColumn, ColumnMap } from './types';
+
+/**
+ * A row projection, usable anywhere a schema is. `$row` is the phantom that carries the type
+ * (`type PostView = typeof PostView.$row`); `$name` is how a manifest or an OpenAPI document
+ * identifies it.
+ */
+export interface EntityView<Row, K extends keyof Row & string>
+  extends StandardSchemaV1<unknown, Pick<Row, K>> {
+  readonly $name: string;
+  readonly $keys: readonly K[];
+  /** Phantom: `type PostView = typeof PostView.$row`. Reading it at runtime throws. */
+  readonly $row: Pick<Row, K>;
+}
+
+/** Dots and underscores only, so the name is a legal `components.schemas` key unescaped. */
+const viewName = (entityName: string, keys: readonly string[]): string =>
+  `${entityName}.view.${keys.join('_')}`;
+
+/**
+ * Bound to an entity as `$view`; never exported as a free `view(entity, keys)`, because two ways
+ * to write the same projection is exactly the ambiguity the `$`-prefixed surface exists to avoid.
+ */
+export const viewFor = <Row, K extends keyof Row & string>(
+  entityName: string,
+  columns: ColumnMap,
+  keys: readonly K[],
+): EntityView<Row, K> => {
+  // Resolved once, at declaration: a key naming no column is the author's typo, and the columns
+  // are listed because the agent reading the error is the one that has to pick the right key.
+  const picked: readonly (readonly [K, AnyColumn])[] = keys.map((key) => {
+    const column = columns[key];
+    if (column === undefined) {
+      throw invariantViolated(
+        entityName,
+        'view',
+        `$view(['${key}']) names no column — pick from: ${Object.keys(columns).join(', ')}`,
+      );
+    }
+    return [key, column] as const;
+  });
+  const name = viewName(entityName, keys);
+
+  const parse = (value: unknown): Pick<Row, K> => {
+    if (typeof value !== 'object' || value === null) {
+      throw invariantViolated(entityName, 'view', `expected an object, got ${String(value)}`);
+    }
+    const input = value as Readonly<Record<string, unknown>>;
+    const projected = {} as Record<K, unknown>;
+    for (const [key, column] of picked) {
+      const given = input[key];
+      if (given === undefined || given === null) {
+        // No default is filled in: a view projects a row that already exists, so an absent
+        // required column is missing data, never a value the projection may invent.
+        if (column.$meta.notNull) throw invariantViolated(entityName, `view.${key}`, 'is required');
+        projected[key] = null;
+        continue;
+      }
+      projected[key] = column.$parse(given);
+    }
+    // Every picked key went through its own column's parser, so this is the derived projection.
+    return projected as Pick<Row, K>;
+  };
+
+  return {
+    '~standard': {
+      version: 1,
+      vendor: 'ultimate',
+      validate: (value) => {
+        try {
+          return { value: parse(value) };
+        } catch (error) {
+          return {
+            issues: [{ message: error instanceof Error ? error.message : String(error) }],
+          };
+        }
+      },
+    },
+    $name: name,
+    $keys: keys,
+    get $row(): Pick<Row, K> {
+      // Type-only, exactly as on the entity. Reading it means a type was meant.
+      throw invariantViolated(
+        entityName,
+        'view.$row',
+        '$row is a type, not a value — use typeof x.$row',
+      );
+    },
+  };
+};