@everystack/model 0.3.0

package/src/model.ts

@@ -0,0 +1,68 @@
+/**
+ * `defineModel` — Layer 2. One call colocates everything about a table: its
+ * fields, its authorization (`abilities`), its mutation hooks, and its relations.
+ *
+ * Functional, not `class extends Model`: best inference, composes with the
+ * functional `field`/`can` builders, and structurally resists the fat-model trap
+ * (a model *declares*; behavior lives in the functions it references).
+ *
+ * Phase 0 returns a plain descriptor. Later phases read it from two directions —
+ * the handler-config derivation (now) and the abilities→contract compiler (Phase 1).
+ */
+
+import type { FieldBuilder } from './field';
+import type { Ability } from './can';
+import type { Relation } from './relations';
+import type { TableConstraint } from './constraints';
+
+/**
+ * Per-table mutation hooks. Imperative function bodies the framework cannot
+ * absorb (purge an S3 object on delete, stamp a column on create) — held
+ * verbatim and passed through to the handler's `hooks`.
+ */
+export interface ModelHooks {
+  beforeCreate?: (...args: any[]) => any;
+  afterCreate?: (...args: any[]) => any;
+  beforeUpdate?: (...args: any[]) => any;
+  afterUpdate?: (...args: any[]) => any;
+  beforeDelete?: (...args: any[]) => any;
+  afterDelete?: (...args: any[]) => any;
+}
+
+export interface ModelDefinition {
+  fields: Record<string, FieldBuilder>;
+  abilities?: Ability[];
+  hooks?: ModelHooks;
+  relations?: Record<string, Relation>;
+  /** Table-level constraints the column-scoped `field()` can't express — composite `unique`, multi-column `check`. */
+  constraints?: TableConstraint[];
+}
+
+export interface ModelDescriptor {
+  /** The Postgres table name (the unit of thought, and of file). */
+  table: string;
+  fields: Record<string, FieldBuilder>;
+  abilities: Ability[];
+  hooks?: ModelHooks;
+  relations: Record<string, Relation>;
+  /** Field names marked `.primaryKey()`, in declaration order (composite-PK aware). */
+  primaryKey: string[];
+  /** Table-level constraints (composite unique, multi-column check), in declaration order. */
+  constraints: TableConstraint[];
+}
+
+export function defineModel(table: string, def: ModelDefinition): ModelDescriptor {
+  const primaryKey = Object.entries(def.fields)
+    .filter(([, f]) => f.spec.isPrimaryKey)
+    .map(([name]) => name);
+
+  return {
+    table,
+    fields: def.fields,
+    abilities: def.abilities ?? [],
+    hooks: def.hooks,
+    relations: def.relations ?? {},
+    primaryKey,
+    constraints: def.constraints ?? [],
+  };
+}

package/src/raw-sql.ts

@@ -0,0 +1,16 @@
+/**
+ * `sql\`…\`` — a raw SQL fragment, branded so the constraint builders accept only an
+ * explicit SQL predicate (never a bare string by accident). Interpolated values are
+ * spliced in verbatim: this is author-time model SQL (the developer's own predicate),
+ * not a runtime query over untrusted input, so there is no parameterization here.
+ */
+
+export interface RawSql {
+  readonly sql: string;
+}
+
+export function sql(strings: TemplateStringsArray, ...values: unknown[]): RawSql {
+  let out = strings[0];
+  for (let i = 0; i < values.length; i++) out += String(values[i]) + strings[i + 1];
+  return { sql: out.trim() };
+}

package/src/relations.ts

@@ -0,0 +1,48 @@
+/**
+ * Relation declarations. `belongsTo` / `hasMany` mirror the handler's
+ * RelationConfig ({ table, from, to, many }), resolved by the derivation.
+ *
+ *   belongsTo(() => Author, 'authorId')   // this.authorId → Author.<pk>
+ *   hasMany(() => Comment, 'postId')      // this.<pk> → Comment.postId
+ *
+ * The target is a thunk so models can reference each other regardless of file or
+ * declaration order.
+ */
+
+import type { ModelDescriptor } from './model';
+
+export interface Relation {
+  kind: 'belongsTo' | 'hasMany';
+  /** Thunk to the related model (forward-reference safe). */
+  target: () => ModelDescriptor;
+  /**
+   * The foreign-key column.
+   * - belongsTo: the FK on THIS table (becomes RelationConfig.from)
+   * - hasMany:   the FK on the TARGET table (becomes RelationConfig.to)
+   */
+  column: string;
+  /**
+   * The key on the other side, when it is not the other table's primary key.
+   * - belongsTo: overrides RelationConfig.to   (default: target pk)
+   * - hasMany:   overrides RelationConfig.from (default: this table's pk)
+   */
+  references?: string;
+}
+
+/** Many-to-one: this row points at one target row via `column`. */
+export function belongsTo(
+  target: () => ModelDescriptor,
+  column: string,
+  references?: string,
+): Relation {
+  return { kind: 'belongsTo', target, column, references };
+}
+
+/** One-to-many: target rows point back at this row via `column`. */
+export function hasMany(
+  target: () => ModelDescriptor,
+  column: string,
+  references?: string,
+): Relation {
+  return { kind: 'hasMany', target, column, references };
+}