@metaobjectsdev/runtime-ts 0.5.0-rc.1

package/src/errors.ts

@@ -0,0 +1,114 @@
+// All errors extend RuntimeError and JSON-serialize via toJSON() — admin UIs and MCP tools
+// surface them as structured JSON, not Error.message strings.
+
+export interface ValidationFailure {
+  field: string;
+  rule: string;
+  message: string;
+  expected?: unknown;
+  received?: unknown;
+}
+
+interface BaseOpts {
+  code?: string;
+  entity?: string;
+  cause?: unknown;
+}
+
+export class RuntimeError extends Error {
+  readonly code: string;
+  readonly entity?: string;
+  override readonly cause?: unknown;
+
+  constructor(message: string, opts: BaseOpts & { code: string }) {
+    super(message);
+    this.name = "RuntimeError";
+    this.code = opts.code;
+    if (opts.entity !== undefined) this.entity = opts.entity;
+    if (opts.cause !== undefined) this.cause = opts.cause;
+  }
+
+  toJSON(): Record<string, unknown> {
+    const out: Record<string, unknown> = { name: this.name, code: this.code, message: this.message };
+    if (this.entity !== undefined) out.entity = this.entity;
+    return out;
+  }
+}
+
+export class ValidationError extends RuntimeError {
+  readonly errors: ValidationFailure[];
+
+  constructor(message: string, opts: { entity?: string; errors: ValidationFailure[]; cause?: unknown }) {
+    super(message, { code: "validation_failed", ...(opts.entity !== undefined ? { entity: opts.entity } : {}), ...(opts.cause !== undefined ? { cause: opts.cause } : {}) });
+    this.name = "ValidationError";
+    this.errors = opts.errors;
+  }
+
+  override toJSON(): Record<string, unknown> {
+    return { ...super.toJSON(), errors: this.errors };
+  }
+}
+
+export class NotFoundError extends RuntimeError {
+  readonly id: unknown;
+
+  constructor(message: string, opts: { entity: string; id: unknown; cause?: unknown }) {
+    super(message, { code: "not_found", entity: opts.entity, ...(opts.cause !== undefined ? { cause: opts.cause } : {}) });
+    this.name = "NotFoundError";
+    this.id = opts.id;
+  }
+
+  override toJSON(): Record<string, unknown> {
+    return { ...super.toJSON(), id: this.id };
+  }
+}
+
+export class ConstraintViolationError extends RuntimeError {
+  readonly kind: "unique" | "foreign_key" | "not_null" | "check";
+  readonly table: string;
+  readonly field?: string;
+  readonly detail?: string;
+
+  constructor(message: string, opts: {
+    kind: "unique" | "foreign_key" | "not_null" | "check";
+    table: string;
+    field?: string;
+    detail?: string;
+    cause?: unknown;
+  }) {
+    super(message, { code: "constraint_violation", ...(opts.cause !== undefined ? { cause: opts.cause } : {}) });
+    this.name = "ConstraintViolationError";
+    this.kind = opts.kind;
+    this.table = opts.table;
+    if (opts.field !== undefined) this.field = opts.field;
+    if (opts.detail !== undefined) this.detail = opts.detail;
+  }
+
+  override toJSON(): Record<string, unknown> {
+    const out: Record<string, unknown> = { ...super.toJSON(), kind: this.kind, table: this.table };
+    if (this.field !== undefined) out.field = this.field;
+    if (this.detail !== undefined) out.detail = this.detail;
+    return out;
+  }
+}
+
+export class MetadataError extends RuntimeError {
+  constructor(message: string, opts: { entity?: string; cause?: unknown } = {}) {
+    super(message, { code: "metadata_error", ...(opts.entity !== undefined ? { entity: opts.entity } : {}), ...(opts.cause !== undefined ? { cause: opts.cause } : {}) });
+    this.name = "MetadataError";
+  }
+}
+
+export class UnsafeNameError extends RuntimeError {
+  readonly value: string;
+
+  constructor(message: string, opts: { value: string }) {
+    super(message, { code: "unsafe_name" });
+    this.name = "UnsafeNameError";
+    this.value = opts.value;
+  }
+
+  override toJSON(): Record<string, unknown> {
+    return { ...super.toJSON(), value: this.value };
+  }
+}

package/src/fastify/index.ts

@@ -0,0 +1,181 @@
+// Fastify adapter for ObjectManager-driven CRUD.
+//
+// Generated route files call `mountCrudRoutes(...)` from here so all the
+// boilerplate (validation, 404 mapping, id parsing, pagination) lives in
+// one tested place rather than being duplicated per entity.
+//
+// Fastify is an OPTIONAL peer dependency. Consumers that don't expose REST
+// pay no runtime cost — this subpath is only loaded when imported.
+//
+// Type-only Fastify imports keep the optional-peer story clean: the .d.ts
+// reference is needed for the public API, but at runtime there's no
+// `require("fastify")`.
+
+import type { FastifyInstance } from "fastify";
+import type { ZodTypeAny } from "zod";
+import type { ObjectManager } from "../object-manager.js";
+import type { Row } from "../persistence-driver.js";
+import type { RouteShorthandOptions } from "fastify";
+
+// ---------------------------------------------------------------------------
+// Public surface
+// ---------------------------------------------------------------------------
+
+export type CrudVerb = "list" | "get" | "create" | "update" | "delete";
+
+export interface CrudRoutesOptions {
+  fastify: FastifyInstance;
+  /** REST resource path, e.g. "/subscribers". */
+  path: string;
+  /** Entity name from metadata, e.g. "Subscriber". */
+  entity: string;
+  /** Zod schema for create payloads (typically `<Entity>InsertSchema`). */
+  insertSchema: ZodTypeAny;
+  /** Zod schema for update payloads (typically `<Entity>UpdateSchema`). */
+  updateSchema: ZodTypeAny;
+  /**
+   * ObjectManager accessor. A function rather than the instance so callers
+   * can keep their lazy-init pattern (load metadata once at startup).
+   */
+  om: () => Promise<ObjectManager>;
+  /**
+   * Limit which verbs are mounted. Defaults to all five. Useful for
+   * read-only resources (`expose: ["list", "get"]`).
+   */
+  expose?: readonly CrudVerb[];
+  /**
+   * Fastify route-level hooks applied to every mounted verb. The most common
+   * use is `preHandler` for auth/authz:
+   *
+   *   routeOptions: { preHandler: requireAdminAuth }
+   *
+   * Anything Fastify accepts on a route options object is valid here
+   * (preHandler, onRequest, preValidation, preParsing, schema, etc.).
+   */
+  routeOptions?: RouteShorthandOptions;
+  /**
+   * HTTP method for the update verb. Defaults to "patch" (semantic partial-
+   * update). Set to "put" to preserve a legacy API contract that already
+   * uses PUT for updates.
+   */
+  updateMethod?: "patch" | "put";
+}
+
+const ALL_VERBS: readonly CrudVerb[] = ["list", "get", "create", "update", "delete"];
+
+/**
+ * Mount the 5 standard REST endpoints for an entity:
+ *
+ *   GET    {path}      → list, with ?limit & ?offset query params
+ *   GET    {path}/:id  → findById
+ *   POST   {path}      → create (validated via insertSchema)
+ *   PATCH  {path}/:id  → partial update (validated via updateSchema)
+ *   DELETE {path}/:id  → delete
+ */
+export function mountCrudRoutes(opts: CrudRoutesOptions): void {
+  const verbs = new Set<CrudVerb>(opts.expose ?? ALL_VERBS);
+  if (verbs.has("list")) mountListRoute(opts);
+  if (verbs.has("get")) mountGetRoute(opts);
+  if (verbs.has("create")) mountCreateRoute(opts);
+  if (verbs.has("update")) mountUpdateRoute(opts);
+  if (verbs.has("delete")) mountDeleteRoute(opts);
+}
+
+// ---------------------------------------------------------------------------
+// Per-verb helpers — exposed so consumers can mix custom routes with the
+// generated CRUD. Each takes the same options bag (minus `expose`).
+// ---------------------------------------------------------------------------
+
+type SingleVerbOptions = Omit<CrudRoutesOptions, "expose">;
+
+/**
+ * Build the route options Fastify wants. Just the consumer's routeOptions
+ * (typed loosely to avoid Fastify's elaborate route-options union here).
+ * Returns an empty object if nothing was provided.
+ */
+function routeOpts(opts: SingleVerbOptions): RouteShorthandOptions {
+  return opts.routeOptions ?? {};
+}
+
+export function mountListRoute(opts: SingleVerbOptions): void {
+  opts.fastify.get(opts.path, routeOpts(opts), async (req) => {
+    const { limit, offset } = req.query as { limit?: string; offset?: string };
+    const readOpts: { limit?: number; offset?: number } = {};
+    if (limit !== undefined) readOpts.limit = Number(limit);
+    if (offset !== undefined) readOpts.offset = Number(offset);
+    return (await opts.om()).findMany(opts.entity, undefined, readOpts);
+  });
+}
+
+export function mountGetRoute(opts: SingleVerbOptions): void {
+  opts.fastify.get(`${opts.path}/:id`, routeOpts(opts), async (req, reply) => {
+    const { id } = req.params as { id: string };
+    const row = await (await opts.om()).findById(opts.entity, parseId(id));
+    return row ?? reply.code(404).send({ error: "not_found" });
+  });
+}
+
+export function mountCreateRoute(opts: SingleVerbOptions): void {
+  opts.fastify.post(opts.path, routeOpts(opts), async (req, reply) => {
+    const parsed = opts.insertSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return reply.code(400).send({ error: "validation", issues: parsed.error.issues });
+    }
+    // Zod returns `unknown` for parsed.data; the schema is authored from the
+    // same metadata that drives ObjectManager, so the shape is guaranteed
+    // compatible — cast at the trust boundary.
+    const row = await (await opts.om()).create(opts.entity, parsed.data as Row);
+    return reply.code(201).send(row);
+  });
+}
+
+export function mountUpdateRoute(opts: SingleVerbOptions): void {
+  const handler = async (
+    req: { params: unknown; body: unknown },
+    reply: {
+      code: (n: number) => { send: (b: unknown) => unknown };
+    },
+  ) => {
+    const { id } = req.params as { id: string };
+    const parsed = opts.updateSchema.safeParse(req.body);
+    if (!parsed.success) {
+      return reply.code(400).send({ error: "validation", issues: parsed.error.issues });
+    }
+    // Use ifMissing: "ignore" so the helper itself owns the 404 mapping
+    // (consistent with mountDeleteRoute). ObjectManager's default behavior
+    // throws NotFoundError, which Fastify would surface as 500.
+    const row = await (await opts.om()).update(opts.entity, parseId(id), parsed.data as Row, {
+      ifMissing: "ignore",
+    });
+    return row ?? reply.code(404).send({ error: "not_found" });
+  };
+  const path = `${opts.path}/:id`;
+  const ro = routeOpts(opts);
+  // biome-ignore lint/suspicious/noExplicitAny: handler signature is generic by design
+  if (opts.updateMethod === "put") {
+    opts.fastify.put(path, ro, handler as any);
+  } else {
+    opts.fastify.patch(path, ro, handler as any);
+  }
+}
+
+export function mountDeleteRoute(opts: SingleVerbOptions): void {
+  opts.fastify.delete(`${opts.path}/:id`, routeOpts(opts), async (req, reply) => {
+    const { id } = req.params as { id: string };
+    const deleted = await (await opts.om()).delete(opts.entity, parseId(id));
+    return deleted ? reply.code(204).send() : reply.code(404).send({ error: "not_found" });
+  });
+}
+
+// ---------------------------------------------------------------------------
+// Helpers
+// ---------------------------------------------------------------------------
+
+/**
+ * Coerce a `:id` path param. Numeric strings parse as Number (covers long/int
+ * PKs); anything else passes through as a string (UUIDs, string keys).
+ */
+export function parseId(raw: string): number | string {
+  const n = Number(raw);
+  return Number.isFinite(n) && raw.trim() !== "" ? n : raw;
+}

package/src/identity-strategy.ts

@@ -0,0 +1,92 @@
+// Generation strategies:
+//  increment → driver-generated by default; caller MAY supply PK (e.g., seeding fixtures, importing legacy data).
+//  uuid      → generated here via crypto.randomUUID() unless caller supplies one.
+//  assigned  → caller must provide PK.
+//  composite → always treated as 'assigned' regardless of the @generation hint.
+
+import type { MetaData } from "@metaobjectsdev/metadata";
+import {
+  TYPE_IDENTITY, IDENTITY_SUBTYPE_PRIMARY,
+  IDENTITY_ATTR_FIELDS, IDENTITY_ATTR_GENERATION,
+  GENERATION_INCREMENT, GENERATION_UUID, GENERATION_ASSIGNED,
+} from "@metaobjectsdev/metadata";
+import { MetadataError, ValidationError } from "./errors.js";
+
+export type IdentityResolution =
+  | { kind: "driver-generated"; values: Record<string, unknown> }
+  | { kind: "preset"; values: Record<string, unknown> };
+
+export function resolveIdentity(entity: MetaData, data: Record<string, unknown>): IdentityResolution {
+  const primary = entity.ownChildren().find(
+    (c) => c.type === TYPE_IDENTITY && c.subType === IDENTITY_SUBTYPE_PRIMARY,
+  );
+  if (!primary) {
+    throw new MetadataError(
+      `Entity '${entity.name}' has no primary identity — cannot resolve PK for create`,
+      { entity: entity.name },
+    );
+  }
+  const fieldsAttr = primary.ownAttr(IDENTITY_ATTR_FIELDS);
+  if (!Array.isArray(fieldsAttr) || fieldsAttr.length === 0) {
+    throw new MetadataError(
+      `Entity '${entity.name}' primary identity has no @fields`,
+      { entity: entity.name },
+    );
+  }
+  const pkFields = fieldsAttr.map(String);
+  const isComposite = pkFields.length > 1;
+  const generation = primary.ownAttr(IDENTITY_ATTR_GENERATION);
+
+  if (isComposite || generation === undefined || generation === GENERATION_ASSIGNED) {
+    const missing = pkFields.filter((f) => data[f] === undefined || data[f] === null);
+    if (missing.length > 0) {
+      throw new ValidationError(
+        `Missing required PK field(s) on '${entity.name}': ${missing.join(", ")}`,
+        {
+          entity: entity.name,
+          errors: missing.map((field) => ({
+            field,
+            rule: "required",
+            message: `PK field '${field}' must be provided when @generation is 'assigned' (or unset, or composite)`,
+          })),
+        },
+      );
+    }
+    const values: Record<string, unknown> = {};
+    for (const f of pkFields) values[f] = data[f];
+    return { kind: "preset", values };
+  }
+
+  if (generation === GENERATION_INCREMENT) {
+    const provided = pkFields.filter((f) => data[f] !== undefined && data[f] !== null);
+    if (provided.length === pkFields.length) {
+      const values: Record<string, unknown> = {};
+      for (const f of pkFields) values[f] = data[f];
+      return { kind: "preset", values };
+    }
+    return { kind: "driver-generated", values: {} };
+  }
+
+  if (generation === GENERATION_UUID) {
+    const values: Record<string, unknown> = {};
+    for (const f of pkFields) {
+      values[f] = data[f] !== undefined && data[f] !== null ? data[f] : crypto.randomUUID();
+    }
+    return { kind: "preset", values };
+  }
+
+  // Unknown @generation values fall back to assigned-style: require the caller to supply the PK.
+  const missing = pkFields.filter((f) => data[f] === undefined || data[f] === null);
+  if (missing.length > 0) {
+    throw new ValidationError(
+      `Missing PK field(s) on '${entity.name}': ${missing.join(", ")}`,
+      {
+        entity: entity.name,
+        errors: missing.map((field) => ({ field, rule: "required", message: `PK field '${field}' is required` })),
+      },
+    );
+  }
+  const values: Record<string, unknown> = {};
+  for (const f of pkFields) values[f] = data[f];
+  return { kind: "preset", values };
+}

package/src/index.ts

@@ -0,0 +1,24 @@
+export { ObjectManager } from "./object-manager.js";
+export type { ObjectManagerOptions, ReadOpts, WriteOpts } from "./object-manager.js";
+
+export type {
+  PersistenceDriver, Dialect, Row, PrimitiveValue,
+  WhereClause, OrderBy,
+  SelectSpec, CountSpec, InsertSpec, InsertManySpec,
+  UpdateSpec, UpdateManySpec, DeleteSpec, DeleteManySpec,
+} from "./persistence-driver.js";
+
+export type { Filter, FilterValue, QueryOpts } from "./query-builder.js";
+
+export type { FieldViewSpec, EntityViewSpec } from "./view.js";
+
+export type { ValidationResult } from "./validator-runner.js";
+export type { ValidationFailure } from "./errors.js";
+export {
+  RuntimeError,
+  ValidationError,
+  NotFoundError,
+  ConstraintViolationError,
+  MetadataError,
+  UnsafeNameError,
+} from "./errors.js";

package/src/n2m-resolver.ts

@@ -0,0 +1,152 @@
+// Two-stage N:M: first query the join entity for FK pairs, then query the target entity for the rows.
+// The relationship declares @joinEntity + @joinFields: [sourceJoinField, targetJoinField].
+
+import type { MetaData } from "@metaobjectsdev/metadata";
+import {
+  TYPE_OBJECT, TYPE_FIELD, TYPE_RELATIONSHIP,
+  RELATIONSHIP_ATTR_CARDINALITY, RELATIONSHIP_ATTR_OBJECT_REF,
+  RELATIONSHIP_ATTR_JOIN_ENTITY, RELATIONSHIP_ATTR_JOIN_FIELDS,
+  CARDINALITY_MANY,
+  resolveColumnName,
+} from "@metaobjectsdev/metadata";
+import { MetadataError } from "./errors.js";
+import { buildSelectSpec, resolvePkFields } from "./query-builder.js";
+import type { SelectSpec, PrimitiveValue, Row } from "./persistence-driver.js";
+
+export interface N2mDescriptor {
+  /** Entity that declares the relationship (source of the lookup; its PK feeds sourceJoinField). */
+  sourceEntityName: string;
+  targetEntityName: string;
+  joinEntityName: string;
+  /** Field name on the join entity holding the source-side FK. */
+  sourceJoinField: string;
+  /** Field name on the join entity holding the target-side FK. */
+  targetJoinField: string;
+}
+
+export interface N2mLazyOutput {
+  joinSpec: SelectSpec;
+  /** Caller runs joinSpec, then passes the rows here to build the target spec. */
+  makeTargetSpec: (joinRows: Row[]) => SelectSpec | null;
+}
+
+export interface N2mBatchOutput {
+  joinSpec: SelectSpec;
+  makeTargetSpec: (joinRows: Row[]) => SelectSpec | null;
+}
+
+/** Returns null if the named relationship is not N:M — caller should try resolveRelationDescriptor. */
+export function resolveN2mDescriptor(
+  sourceEntity: MetaData,
+  relationName: string,
+  root: MetaData,
+): N2mDescriptor | null {
+  for (const child of sourceEntity.ownChildren()) {
+    if (child.type !== TYPE_RELATIONSHIP) continue;
+    if (child.name !== relationName) continue;
+    if (child.ownAttr(RELATIONSHIP_ATTR_CARDINALITY) !== CARDINALITY_MANY) continue;
+    const targetEntityName = child.ownAttr(RELATIONSHIP_ATTR_OBJECT_REF) as string | undefined;
+    const joinEntityName = child.ownAttr(RELATIONSHIP_ATTR_JOIN_ENTITY) as string | undefined;
+    const joinFields = child.ownAttr(RELATIONSHIP_ATTR_JOIN_FIELDS);
+    if (!targetEntityName || !joinEntityName || !Array.isArray(joinFields) || joinFields.length !== 2) {
+      throw new MetadataError(
+        `N:M relationship '${relationName}' on '${sourceEntity.name}' requires @objectRef + @joinEntity + @joinFields: [sourceFk, targetFk]`,
+        { entity: sourceEntity.name },
+      );
+    }
+    const targetExists = root.ownChildren().some((c) => c.type === TYPE_OBJECT && c.name === targetEntityName);
+    if (!targetExists) {
+      throw new MetadataError(`Target entity '${targetEntityName}' not found`, { entity: sourceEntity.name });
+    }
+    const joinExists = root.ownChildren().some((c) => c.type === TYPE_OBJECT && c.name === joinEntityName);
+    if (!joinExists) {
+      throw new MetadataError(`Join entity '${joinEntityName}' not found`, { entity: sourceEntity.name });
+    }
+    return {
+      sourceEntityName: sourceEntity.name,
+      targetEntityName,
+      joinEntityName,
+      sourceJoinField: String(joinFields[0]),
+      targetJoinField: String(joinFields[1]),
+    };
+  }
+  return null;
+}
+
+export function buildN2mLazySpecs(
+  desc: N2mDescriptor,
+  sourceRecord: Row,
+  root: MetaData,
+): N2mLazyOutput {
+  const joinEntity = mustGetEntity(root, desc.joinEntityName);
+  const targetEntity = mustGetEntity(root, desc.targetEntityName);
+  const sourcePkField = resolvePkFields(mustGetEntity(root, desc.sourceEntityName))[0]!;
+  const sourcePkValue = sourceRecord[sourcePkField];
+
+  const joinSpec = buildSelectSpec(joinEntity, { [desc.sourceJoinField]: sourcePkValue as PrimitiveValue }, {});
+
+  const makeTargetSpec = (joinRows: Row[]): SelectSpec | null => {
+    const targetIds = collectTargetIds(joinRows, desc.targetJoinField, joinEntity);
+    if (targetIds.length === 0) return null;
+    const targetPkField = resolvePkFields(targetEntity)[0]!;
+    return buildSelectSpec(targetEntity, { [targetPkField]: targetIds }, {});
+  };
+
+  return { joinSpec, makeTargetSpec };
+}
+
+export function buildN2mBatchSpecs(
+  desc: N2mDescriptor,
+  sourceRecords: Row[],
+  root: MetaData,
+): N2mBatchOutput {
+  const joinEntity = mustGetEntity(root, desc.joinEntityName);
+  const targetEntity = mustGetEntity(root, desc.targetEntityName);
+  const sourcePkField = resolvePkFields(mustGetEntity(root, desc.sourceEntityName))[0]!;
+  const sourceIds = collectIds(sourceRecords, sourcePkField);
+
+  const joinSpec = buildSelectSpec(joinEntity, { [desc.sourceJoinField]: sourceIds }, {});
+
+  const makeTargetSpec = (joinRows: Row[]): SelectSpec | null => {
+    const targetIds = collectTargetIds(joinRows, desc.targetJoinField, joinEntity);
+    if (targetIds.length === 0) return null;
+    const targetPkField = resolvePkFields(targetEntity)[0]!;
+    return buildSelectSpec(targetEntity, { [targetPkField]: targetIds }, {});
+  };
+
+  return { joinSpec, makeTargetSpec };
+}
+
+function mustGetEntity(root: MetaData, name: string): MetaData {
+  const e = root.ownChildren().find((c) => c.type === TYPE_OBJECT && c.name === name);
+  if (!e) throw new MetadataError(`Entity '${name}' not found`, { entity: name });
+  return e;
+}
+
+function collectIds(records: Row[], pkField: string): (string | number)[] {
+  const seen = new Set<PrimitiveValue>();
+  for (const r of records) {
+    const v = r[pkField];
+    if (v === null || v === undefined) continue;
+    seen.add(v as PrimitiveValue);
+  }
+  return [...seen] as (string | number)[];
+}
+
+function collectTargetIds(joinRows: Row[], targetJoinField: string, joinEntity: MetaData): (string | number)[] {
+  // joinRows are raw column-keyed (driver hasn't been to-JS-row'd yet); resolve the metadata field name to its DB column.
+  const dbColumn = resolveJoinColumnName(joinEntity, targetJoinField);
+  const seen = new Set<PrimitiveValue>();
+  for (const r of joinRows) {
+    const v = r[dbColumn];
+    if (v === null || v === undefined) continue;
+    seen.add(v as PrimitiveValue);
+  }
+  return [...seen] as (string | number)[];
+}
+
+export function resolveJoinColumnName(joinEntity: MetaData, fieldName: string): string {
+  const field = joinEntity.ownChildren().find((c) => c.type === TYPE_FIELD && c.name === fieldName);
+  if (!field) throw new MetadataError(`Join field '${fieldName}' not on '${joinEntity.name}'`);
+  return resolveColumnName(field);
+}