@stonyx/orm 0.3.2-beta.16 → 0.3.2-beta.160

package/src/store.ts

@@ -1,5 +1,5 @@
 import Orm, { relationships } from '@stonyx/orm';
-import { TYPES, getHasManyRegistry, getBelongsToRegistry, getPendingRegistry } from './relationships.js';
+import { TYPES, getHasManyRegistry, getBelongsToRegistry, getPendingRegistry, getPendingBelongsToRegistry } from './relationships.js';
 import ViewResolver from './view-resolver.js';
 
 interface UnloadOptions {
@@ -64,7 +64,7 @@ export default class Store {
   get(key: string): Map<number | string, unknown> | undefined;
   get(key: string, id: number | string): unknown;
   get(key: string, id?: number | string): Map<number | string, unknown> | unknown | undefined {
-    if (!id) return this.data.get(key);
+    if (id === undefined) return this.data.get(key);
 
     return this.data.get(key)?.get(id);
   }
@@ -170,14 +170,15 @@ export default class Store {
     this.data.set(key, value);
   }
 
-  remove(key: string, id?: number | string): void {
+  remove(key: string, id?: number | string, options?: { _skipAutoPersist?: boolean }): void {
     // Guard: read-only views cannot have records removed
     if (Orm.instance?.isView?.(key)) {
       throw new Error(`Cannot remove records from read-only view '${key}'`);
     }
 
-    // Auto-persist delete to SQL
-    if (id && Orm.instance?.sqlDb) {
+    // Auto-persist delete to SQL (fire-and-forget) — skipped when the
+    // request path handles persist itself to avoid double-delete.
+    if (id && Orm.instance?.sqlDb && !options?._skipAutoPersist) {
       Orm.instance.sqlDb.persist('delete', key, { recordId: id }, {}).catch((err: unknown) => {
         Orm.instance.emitPersistError({
           operation: 'delete',
@@ -193,6 +194,44 @@ export default class Store {
     this.unloadAllRecords(key);
   }
 
+  /**
+   * Evict a record from the store with full relationship registry cleanup.
+   * The caller retains its reference to the returned record, which is the
+   * contract memory:false post-persist eviction relies on.
+   *
+   * @param registryId - The ID used when the record's relationships were
+   *   registered. For SQL models with pending IDs, this is the original
+   *   negative pending ID (before the adapter re-keyed to the real DB ID).
+   */
+  evictRecord(modelName: string, id: unknown, registryId?: unknown): void {
+    const modelStore = this.data.get(modelName);
+    if (!modelStore) return;
+
+    if (typeof id !== 'string' && typeof id !== 'number') return;
+    const raw = modelStore.get(id);
+    if (!raw || !isStoreRecord(raw)) return;
+
+    const visited = new Set([`${modelName}:${id}`]);
+
+    // Remove from hasMany arrays and nullify belongsTo references using current ID
+    // (the adapter updates record.id, so value-based matches need the current ID)
+    this._removeFromHasManyArrays(modelName, id, visited);
+    this._nullifyBelongsToReferences(modelName, id, visited);
+
+    // Clean up relationship registry entries using the registry key
+    // (belongsTo/hasMany registries were keyed by the ID at registration time,
+    // which may differ from the current ID if SQL persist re-keyed the record)
+    const cleanupId = registryId ?? id;
+    this._cleanupRelationshipRegistries(modelName, cleanupId);
+
+    // If registryId differs from id, also clean with current id as safety net
+    if (registryId !== undefined && registryId !== id) {
+      this._cleanupRelationshipRegistries(modelName, id);
+    }
+
+    modelStore.delete(id);
+  }
+
   unloadRecord(model: string, id: unknown, options: UnloadOptions = {}): void {
     const modelStore = this.data.get(model);
 
@@ -219,7 +258,6 @@ export default class Store {
       this._removeFromHasManyArrays(modelName, recordId, visited);
       this._nullifyBelongsToReferences(modelName, recordId, visited);
       this._cleanupRelationshipRegistries(modelName, recordId);
-      recordToUnload.clean();
 
       this.data.get(modelName)?.delete(recordId as string | number);
     }
@@ -308,6 +346,30 @@ export default class Store {
 
     const pendingMap = getPendingRegistry().get(modelName);
     if (pendingMap) pendingMap.delete(recordId);
+
+    // Clean pendingBelongsTo entries in both directions
+    const pendingBelongsToMap = getPendingBelongsToRegistry();
+    if (pendingBelongsToMap) {
+      // Direction 1: evicted record was the TARGET others were waiting for
+      const targetEntries = pendingBelongsToMap.get(modelName);
+      if (targetEntries) targetEntries.delete(recordId);
+
+      // Direction 2: evicted record was the SOURCE with unresolved forward-references
+      for (const [, targetIdMap] of pendingBelongsToMap) {
+        for (const [targetId, entries] of targetIdMap) {
+          if (!Array.isArray(entries)) continue;
+          const filtered = entries.filter((e: unknown) => {
+            const entry = e as { sourceModelName?: string; relationshipId?: unknown };
+            return !(entry.sourceModelName === modelName && entry.relationshipId === recordId);
+          });
+          if (filtered.length === 0) {
+            targetIdMap.delete(targetId);
+          } else if (filtered.length < entries.length) {
+            targetIdMap.set(targetId, filtered);
+          }
+        }
+      }
+    }
   }
 
   /**

package/src/types/orm-types.ts

@@ -18,6 +18,7 @@ export interface OrmMysqlConfig {
   connectionLimit?: number;
   migrationsDir?: string;
   migrationsTable?: string;
+  autoMigrate?: boolean;
   [key: string]: unknown;
 }
 
@@ -30,6 +31,7 @@ export interface OrmPostgresConfig {
   connectionLimit?: number;
   migrationsDir?: string;
   migrationsTable?: string;
+  autoMigrate?: boolean;
   [key: string]: unknown;
 }
 
@@ -48,6 +50,13 @@ export interface OrmRestServerConfig {
   metaRoute: boolean;
 }
 
+export interface OrmDynamoDBConfig {
+  region?: string;
+  endpoint?: string;
+  tablePrefix?: string;
+  [key: string]: unknown;
+}
+
 export interface OrmSection {
   db: OrmDbConfig;
   paths: OrmPaths;
@@ -55,6 +64,9 @@ export interface OrmSection {
   mysql?: OrmMysqlConfig;
   postgres?: OrmPostgresConfig;
   timescale?: OrmPostgresConfig;
+  dynamodb?: OrmDynamoDBConfig;
+  logColor?: string;
+  logMethod?: string;
   [key: string]: unknown;
 }
 
@@ -77,7 +89,15 @@ export interface OrmRecord {
   __model?: { __name: string };
   __data: Record<string, unknown> & { id?: string | number; __pendingSqlId?: boolean };
   __relationships: Record<string, unknown>;
-  toJSON?(options?: { fields?: Set<string>; baseUrl?: string }): Record<string, unknown>;
+  /**
+   * `linkage` is an ALREADY-RESOLVED decision supplied by a caller that holds
+   * the request (abofs/stonyx-orm#234): return `false` for a related record and
+   * its `{ type, id }` is dropped from `relationships.*.data`. Omitting it is
+   * the default, and the default is the pre-#234 document unchanged -- this
+   * method is also the `JSON.stringify` hook, so an implicit caller has no
+   * syntactic place to pass it (abofs/stonyx-orm#230).
+   */
+  toJSON?(options?: { fields?: Set<string>; baseUrl?: string; linkage?: LinkageFilter }): Record<string, unknown>;
   [key: string]: unknown;
 }
 
@@ -156,3 +176,250 @@ export interface SnapshotEntry {
   source?: string;
   viewQuery?: string;
 }
+
+/**
+ * The shapes a consumer `access()` predicate may return.
+ *
+ * - `false` (or any falsy value) -- deny, 403.
+ * - `true` -- allow, with no per-record filter.
+ * - a permission string or array of them, drawn from the same four verbs as
+ *   {@link AccessContext.operation}. A BARE STRING IS ONE PERMISSION, not a
+ *   grant of all four.
+ * - a `(record) => boolean` predicate -- allow, and filter every record the
+ *   request touches through it.
+ *
+ * Anything else fails CLOSED. See `src/orm-request.ts` `auth()`.
+ */
+export type AccessMethod = string | boolean | string[] | ((record: unknown) => boolean);
+
+/**
+ * The closed vocabulary `AccessContext.operation` is drawn from
+ * (abofs/stonyx-orm#202).
+ *
+ * A literal union rather than `string`, so the guarantee the prose makes is the
+ * one the compiler enforces: a consumer who writes `operation === 'GET'` or
+ * `operation === 'get'` -- the hook vocabulary, see below -- gets a compile
+ * error instead of a comparison that never matches. A predicate that stops
+ * matching falls through to the permission array, so the misreading is
+ * fail-open shaped.
+ *
+ * In-repo precedent: `PersistErrorDetail.operation` in `src/main.ts`.
+ */
+export type AccessOperation = 'read' | 'create' | 'update' | 'delete';
+
+/**
+ * The structural facts about the request being authorised, handed to a consumer
+ * `access()` predicate as its SECOND argument (abofs/stonyx-orm#202).
+ *
+ * These are the facts the framework already holds at authorisation time. Before
+ * #202 a consumer had to reconstruct both of them by string-matching a URL, and
+ * five independent fail-open variants of that reconstruction were found in one
+ * three-line documented example -- each one wrong in the direction that GRANTS
+ * access. Read these instead; there is nothing to parse and no variant to miss.
+ *
+ * `record` is deliberately NOT a member. `auth()` runs after route matching but
+ * before any handler executes (`@stonyx/rest-server` `src/request.ts:58-60`),
+ * so nothing has been fetched yet -- carrying a record here would force a
+ * pre-fetch on every request. It is also unnecessary: the `(record) => boolean`
+ * return shape of {@link AccessMethod} already IS the per-record hook, applied
+ * by the handlers. Auth-time and record-time are separate decision points.
+ */
+export interface AccessContext {
+  /**
+   * The model this route was mounted for, e.g. `'owner'` or `'phone-number'`.
+   *
+   * Model names are kebab-case, as declared under `config.orm.paths.model` and
+   * keyed in the store -- NOT the pluralised, mount-prefixed route name. It is
+   * read from the `OrmRequest` instance and is never derived from the request
+   * target, so a mount prefix, a case-varied path, a query string or an
+   * absolute-form request-target cannot change it.
+   */
+  model: string;
+
+  /**
+   * The operation being authorised. Exactly one of the four {@link
+   * AccessOperation} verbs, or `undefined`. These are exactly the values of
+   * `methodAccessMap` in `src/orm-request.ts`, which is also what the
+   * permission-array return shape is matched against -- so the two forms cannot
+   * disagree.
+   *
+   * NOT the hook vocabulary. `HookContext.operation` (`src/hooks.ts`) carries
+   * `'list' | 'get' | 'create' | 'update' | 'delete'` on an identically-named
+   * key of an identically-shaped context object, and the access vocabulary
+   * collapses `list` and `get` into `'read'`. For one `GET /animals/1` a hook
+   * sees `'get'` and `access()` sees `'read'`. "No second vocabulary" is a
+   * statement about the ACCESS path only.
+   *
+   * `undefined` when the dispatched method has no entry in that map. Express
+   * delivers `HEAD` to the `GET` handler, so this is reachable. It is left
+   * undefined rather than defaulted on purpose: a fabricated `'read'` would
+   * turn an unclassified request into an authorised one.
+   *
+   * The KEY is required even though the value may be undefined: `auth()` always
+   * sets it, and a context that simply omitted it would be indistinguishable
+   * from one that classified the request and found nothing.
+   */
+  operation: AccessOperation | undefined;
+
+  /**
+   * The record this route was addressed to, as the store key -- or `null` on a
+   * collection route, which is addressed to no record (abofs/stonyx-orm#236).
+   *
+   * IT IS ALREADY DECODED, AND THAT IS THE WHOLE POINT. Express decodes route
+   * PARAMETERS while leaving `request.path` raw, so a consumer comparing
+   * `request.path` against a literal compares an undecoded string against a
+   * decoded dispatch. `GET /owners/%61rchived` reached such a comparison as
+   * `/%61rchived`, walked past a `/archived` deny, and was dispatched as the
+   * record `archived` -- 200 with the record in full, and `DELETE` destroyed
+   * it, unauthenticated. 255 non-canonical spellings of an 8-character id
+   * decode to the same key, so a deny-list of spellings is the wrong shape.
+   *
+   * SO DO NOT NORMALISE THIS, AND DO NOT NORMALISE ANYTHING ELSE INSTEAD:
+   *
+   * - Do NOT decode it. Express decodes exactly ONCE, which is what a route
+   *   parameter means. `GET /owners/%2561rchived` is the legitimate id
+   *   `%61rchived`, not a second-order spelling of `archived`; a predicate that
+   *   decoded until stable would deny a record it was never asked about.
+   * - Do NOT case-fold it. A record id is a VALUE, not a literal route segment,
+   *   and express's `case sensitive routing` governs literal segments only.
+   *   With a distinct owner seeded at `ARCHIVED`, `.toLowerCase()` was measured
+   *   wrong in BOTH directions at once: `GET /owners/ARCHIVED` 403 (a false
+   *   deny, on the wrong record) and `GET /owners/%41RCHIVED` 200 (a false
+   *   allow, on that same record).
+   * - Do NOT derive it from `request.path` or the request target. Decoding the
+   *   whole path decodes THEN splits, while the router splits THEN decodes, so
+   *   `/owners/archived%2fx` -- a genuinely distinct record whose id is
+   *   `archived/x` -- was measured over-denied 403.
+   *
+   * IT IS `getId(request.params)`, BYTE FOR BYTE -- the same single coercion
+   * the store lookup uses, exactly as `operation` is the same `methodAccessMap`
+   * lookup the permission-array branch uses. The predicate and the dispatch
+   * therefore cannot disagree about which record a request addresses. Handing
+   * over the raw `request.params.id` instead would reintroduce that divergence
+   * on hex-shaped ids: `GET /animals/0x2391` looks up record `9105`.
+   *
+   * It inherits abofs/stonyx-orm#209 along with that coercion -- on a model
+   * declaring `id = attr('string')`, `'9107'` arrives here as the number
+   * `9107`. That is consistency WITH THE LOOKUP, which is the property this key
+   * exists to buy; it is not a defect to repair here.
+   *
+   * `null`, not `undefined`, on a collection route -- and the KEY IS ALWAYS
+   * PRESENT, the same rule `operation` states above. `auth()` always sets it,
+   * so a context arriving WITHOUT the key did not come from `auth()`: it was
+   * hand-assembled by a caller resolving the predicate through
+   * `Orm.instance.getAccess()`. That absence stays a distinguishable, deniable
+   * signal only because the framework never produces it.
+   *
+   * IT DISAGREES WITH THE HOOK VOCABULARY, AND NOT ONLY ON THE ABSENCE
+   * SPELLING. `HookContext.recordId` (`src/hooks.ts`) is an identically-named
+   * key on an identically-shaped context object, which is the exact
+   * configuration that makes `operation` fail-open shaped -- a hook sees
+   * `'get'` where `access()` sees `'read'`. An earlier revision of THIS
+   * docblock asserted the opposite ("here they AGREE... they differ in ONE way
+   * and it is the absence spelling"). That was measured false, in the fail-open
+   * direction, and it is corrected here rather than deleted.
+   *
+   * MEASURED over the live dispatch, before-hooks registered for all five
+   * operations on one model:
+   *
+   *     before:list    key ABSENT      ('recordId' in context === false)
+   *     before:get     key ABSENT      params={"id":"visible1"}
+   *     before:create  key ABSENT
+   *     before:update  key ABSENT      params={"id":"visible2"}
+   *     before:delete  recordId="visible3"
+   *     after:delete   recordId="visible3"
+   *
+   * `_withHooks` assigns `context.recordId` at exactly TWO sites in
+   * `src/orm-request.ts`, and BOTH sit inside an `operation === 'delete'`
+   * branch. So the two keys differ in COVERAGE, on four of five operations: on
+   * a hook context the key is absent for get, list, create and update, while
+   * this key is present on every route `auth()` classifies. The absence
+   * spelling is the smaller half of the difference, not the whole of it.
+   *
+   * AND THAT INVERTS THE ARGUMENT ABOVE WHEN IT IS READ ACROSS THE TWO. Here,
+   * a missing `recordId` means "did not come from `auth()`" and is deniable.
+   * On a hook context it means "this is a get / list / create / update" -- an
+   * ordinary request. A consumer who writes the hook-side half of the same
+   * rule --
+   *
+   *     beforeHook('update', 'owner', ctx => ctx.recordId === 'archived' ? 403 : undefined)
+   *
+   * -- gets a deny that NEVER FIRES: measured, `PATCH /owners/visible2` -> 200,
+   * with `ctx.recordId === undefined` while the addressed record sits in
+   * `ctx.params`. The hook side is abofs/stonyx-orm#242 and is deliberately not
+   * repaired here. A predicate must not read `undefined` here as "collection",
+   * and nothing in this contract makes it safe to read the two keys as one key.
+   *
+   * IT NAMES WHICH RECORD OF THE MODEL BEING ASKED ABOUT, NOT WHICH SURFACE,
+   * AND THE ANSWER DEPENDS ON WHICH MODEL IS BEING ASKED ABOUT.
+   *
+   * For the ask about the ROUTE'S OWN model, all three of `GET /owners/gina`,
+   * `GET /owners/gina/pets` and `GET /owners/gina/relationships/pets` carry
+   * `recordId: 'gina'` -- `auth()` reads it off `request.params`.
+   *
+   * FOR THE ASK ABOUT A RELATED MODEL, IT IS `null`, AND THAT IS A LIMIT ON
+   * WHAT A PREDICATE CAN EXPRESS (abofs/stonyx-orm#232). The two relationship
+   * route families resolve the RELATED model's own predicate -- `animal` on
+   * `GET /owners/gina/pets`, `owner` on `GET /animals/4/owner` -- and that ask
+   * carries `recordId: null` while `request.params` names a record of a
+   * DIFFERENT model. So a predicate answering about a related model gets the
+   * model name, the operation and the request, and CANNOT branch on which
+   * related record it is being asked about.
+   *
+   * The rule, so it is not re-derived wrong: `recordId` may name a record only
+   * where the route addresses exactly one record OF THE MODEL BEING ASKED
+   * ABOUT. A `hasMany` related-resource route returns many records of one type
+   * and the verdict is resolved ONCE PER TYPE, before any record is examined --
+   * seeding it from a record would let the first one decide for all of them.
+   *
+   * What still works, and what does not, is pinned as behaviour by `#232 AC10`
+   * in test/integration/orm-test.ts and stated for consumers in README.md:
+   * model-level denies work, request-level denies work, and the per-record
+   * FILTER shape works because `access()` may return a function and that
+   * function receives the whole record. Branching on identity BEFORE returning
+   * does not.
+   *
+   * `?include=` is a separate surface and is abofs/stonyx-orm#233 / #235.
+   */
+  recordId: string | number | null;
+}
+
+/**
+ * A consumer `access()` predicate.
+ *
+ * The second argument is ADDITIVE: JavaScript ignores extra arguments, so every
+ * pre-#202 single-argument predicate keeps working untouched. Changing the
+ * FIRST argument instead would have been the breaking form, and a predicate
+ * that can no longer identify its collection falls through to a full CRUD
+ * grant -- so the "safer" breaking change would have converted every unmigrated
+ * predicate into a fail-open.
+ *
+ * `context` is nonetheless REQUIRED in the type, and that costs back-compat
+ * nothing. TypeScript already lets a fewer-parameter implementation satisfy a
+ * more-parameter signature, so an arity-1 predicate assigns to this type
+ * cleanly -- measured under `--strict`. What the `?` bought was the opposite of
+ * safety: it silently permitted `getAccess('animal')?.(request)` at the CALL
+ * site, i.e. exactly the omission {@link AccessContext} exists to prevent, and
+ * that call gets the model-wrong answer. Required, a caller that drops the
+ * context gets `TS2554: Expected 2 arguments, but got 1`.
+ */
+export type AccessFunction = (request: unknown, context: AccessContext) => AccessMethod;
+
+/**
+ * A resolved, request-scoped linkage decision: may `record` of model `type` be
+ * NAMED, by id, inside another model's document (abofs/stonyx-orm#234)?
+ *
+ * Arity is `(type, record)` and not `(type, id)` because the per-record filter
+ * a consumer returns is handed the RECORD -- this repo's own fixture reads
+ * `record.owner?.id`, not just `record.id`. The `(type, id)` pair is the CACHE
+ * key inside `createLinkageFilter`, not the input.
+ *
+ * DECLARED HERE, with the rest of the access vocabulary, and imported by every
+ * site that names it. It had three structurally-identical hand-written copies
+ * (`access-verdict.ts`, `record.ts`, `OrmRecord.toJSON` below) bridged to each
+ * other by nothing, so a drift in nullability or a widening of `type` would
+ * have landed on one and not the others -- which is the same "second,
+ * unreviewed vocabulary" failure `src/access-verdict.ts` exists to prevent, one
+ * level up in the type system.
+ */
+export type LinkageFilter = (type: string, record: unknown) => boolean;

package/src/types/stonyx-rest-server.d.ts

@@ -5,7 +5,20 @@ declare module '@stonyx/rest-server' {
 
   interface RouteOptions {
     name: string;
-    options?: { model: string; access: (request: unknown) => unknown } | Record<string, unknown>;
+    /**
+     * `access` is the two-argument post-#202 shape. This is the THIRD place the
+     * contract is declared (`AccessInstance.access` in
+     * `src/setup-rest-server.ts` and `OrmRequest.access` in
+     * `src/orm-request.ts` are the other two) and it is the one `mountRoute` is
+     * actually called through, at `src/setup-rest-server.ts`. It kept the
+     * pre-#202 single-argument signature after the other two migrated; the
+     * union with `Record<string, unknown>` meant nothing broke, which is
+     * exactly why it would have drifted silently.
+     *
+     * Spelled structurally rather than as `AccessFunction`: an ambient
+     * `declare module` block cannot carry an `import type`.
+     */
+    options?: { model: string; access: (request: unknown, context: { model: string; operation: string | undefined }) => unknown } | Record<string, unknown>;
   }
 
   export default class RestServer {

package/src/types/stonyx.d.ts

@@ -5,7 +5,13 @@ declare module 'stonyx/config' {
 }
 
 declare module 'stonyx/log' {
-  const log: Record<string, ((...args: unknown[]) => void) | undefined>;
+  interface Log {
+    db(message: string): void;
+    error(message: string, ...args: unknown[]): void;
+    defineType(type: string, setting: string, options?: Record<string, unknown> | null): void;
+    [key: string]: ((...args: unknown[]) => void) | undefined;
+  }
+  const log: Log;
   export default log;
 }
 

package/src/utils.ts

@@ -20,3 +20,53 @@ export function pluralize(word: string): string {
 
   return basePluralize(word);
 }
+
+/**
+ * The highest NUMERIC id held by a set of records, or `0` when there is none.
+ *
+ * ONE COPY, and the duplication it replaces is the reason it lives here. Three
+ * near-identical reduces existed at once: `assignRecordId` (server-assigned id
+ * selection), `StandaloneDB.create` (src/standalone-db.ts) and the #203 test
+ * helper. `docs/improvements.md`'s standing WET Code category prescribes
+ * exactly this remedy -- extract into the module that already acts as the
+ * shared utility -- and `assignRecordId` already imported `isOrmRecord` from
+ * here.
+ *
+ * NON-NUMBERS ARE SKIPPED RATHER THAN COERCED TO `0`, AND THAT IS STYLISTIC.
+ * `StandaloneDB`'s shape mapped them to `0`, which can never beat a seed of
+ * `0`. Measured over eleven input classes (`[]`, `1`, `NaN`, `'5'`, `'abc'`,
+ * `-3`, `0`, `null`, `undefined`, `Infinity`, and mixed arrays) the two shapes
+ * produce IDENTICAL output on every one. In particular `typeof NaN` is
+ * `'number'`, so NEITHER shape coerces `NaN` -- both reject it on `NaN > max`,
+ * which is `false`. An earlier revision of this code asserted that the skip was
+ * what made the `NaN` case work; it is not, the comparison is, and that claim
+ * has been removed rather than left standing.
+ *
+ * WHAT IS LOAD-BEARING is that this is not `Math.max(...ids)`. `Math.max`
+ * returns `NaN` if any operand is `NaN`, and a record CAN be held under the key
+ * `NaN` -- so the obvious fix assigns `NaN`, lands on that slot and overwrites
+ * it, which is abofs/stonyx-orm#203 in a new disguise. Pinned by
+ * test/unit/assign-record-id-test.ts AC2; before that file existed the whole
+ * suite scored 951/0 under exactly that fix.
+ */
+export function maxNumericId(records: { id?: unknown }[]): number {
+  return records.reduce((max: number, record) => {
+    const { id } = record;
+
+    return typeof id === 'number' && id > max ? id : max;
+  }, 0);
+}
+
+/**
+ * The message prefix `assignRecordId` throws with when no free id can be
+ * derived for a model, and the ONE string `createHandler` matches on to answer
+ * `409` instead of letting the rejection reach express's default handler.
+ *
+ * It lives here rather than in either file because both need it and neither
+ * should own a copy: a literal in two places is how the two id coercions in
+ * orm-request.ts drifted apart (see `coerceId`). The repo has no error codes
+ * and no custom error classes -- 24 bare `throw new Error` sites across `src/`
+ * -- so a shared prefix is the narrowest way to make ONE failure distinguishable
+ * without inventing an error taxonomy this codebase does not use.
+ */
+export const NO_FREE_ID_ERROR = 'Cannot assign record ID: no free id available';

package/config/environment.ts

@@ -1,91 +0,0 @@
-const {
-  ORM_ACCESS_PATH,
-  ORM_MODEL_PATH,
-  ORM_REST_ROUTE,
-  ORM_SERIALIZER_PATH,
-  ORM_TRANSFORM_PATH,
-  ORM_VIEW_PATH,
-  ORM_USE_REST_SERVER,
-  DB_AUTO_SAVE,
-  DB_FILE,
-  DB_MODE,
-  DB_DIRECTORY,
-  DB_SCHEMA_PATH,
-  DB_SAVE_INTERVAL,
-  MYSQL_HOST,
-  MYSQL_PORT,
-  MYSQL_USER,
-  MYSQL_PASSWORD,
-  MYSQL_DATABASE,
-  MYSQL_CONNECTION_LIMIT,
-  MYSQL_MIGRATIONS_DIR,
-  PG_HOST,
-  PG_PORT,
-  PG_USER,
-  PG_PASSWORD,
-  PG_DATABASE,
-  PG_CONNECTION_LIMIT,
-  PG_MIGRATIONS_DIR,
-  TIMESCALE_HOST,
-  TIMESCALE_PORT,
-  TIMESCALE_USER,
-  TIMESCALE_PASSWORD,
-  TIMESCALE_DATABASE,
-  TIMESCALE_CONNECTION_LIMIT,
-  TIMESCALE_MIGRATIONS_DIR,
-} = process.env;
-
-export default {
-  logColor: 'white',
-  logMethod: 'db',
-  
-  db: {
-    autosave: DB_AUTO_SAVE ?? 'false', // 'true' (cron interval), 'false' (disabled), 'onUpdate' (save after each write op)
-    file: DB_FILE ?? 'db.json',
-    mode: DB_MODE ?? 'file', // 'file' (single db.json) or 'directory' (one file per collection)
-    directory: DB_DIRECTORY ?? 'db', // directory name for collection files when mode is 'directory'
-    saveInterval: DB_SAVE_INTERVAL ?? 60 * 60, // 1 hour
-    schema: DB_SCHEMA_PATH ?? './config/db-schema.js'
-  },
-  paths: {
-    access: ORM_ACCESS_PATH ?? './access', // Optional for restServer access hooks
-    model: ORM_MODEL_PATH ?? './models',
-    serializer: ORM_SERIALIZER_PATH ?? './serializers',
-    transform: ORM_TRANSFORM_PATH ?? './transforms',
-    view: ORM_VIEW_PATH ?? './views'
-  },
-  mysql: MYSQL_HOST ? {
-    host: MYSQL_HOST ?? 'localhost',
-    port: parseInt(MYSQL_PORT ?? '3306'),
-    user: MYSQL_USER ?? 'root',
-    password: MYSQL_PASSWORD ?? '',
-    database: MYSQL_DATABASE ?? 'stonyx',
-    connectionLimit: parseInt(MYSQL_CONNECTION_LIMIT ?? '10'),
-    migrationsDir: MYSQL_MIGRATIONS_DIR ?? 'migrations',
-    migrationsTable: '__migrations',
-  } : undefined,
-  postgres: PG_HOST ? {
-    host: PG_HOST ?? 'localhost',
-    port: parseInt(PG_PORT ?? '5432'),
-    user: PG_USER ?? 'postgres',
-    password: PG_PASSWORD ?? '',
-    database: PG_DATABASE ?? 'stonyx',
-    connectionLimit: parseInt(PG_CONNECTION_LIMIT ?? '10'),
-    migrationsDir: PG_MIGRATIONS_DIR ?? 'migrations',
-    migrationsTable: '__migrations',
-  } : undefined,
-  timescale: TIMESCALE_HOST ? {
-    host: TIMESCALE_HOST ?? 'localhost',
-    port: parseInt(TIMESCALE_PORT ?? '5432'),
-    user: TIMESCALE_USER ?? 'postgres',
-    password: TIMESCALE_PASSWORD ?? '',
-    database: TIMESCALE_DATABASE ?? 'stonyx',
-    connectionLimit: parseInt(TIMESCALE_CONNECTION_LIMIT ?? '10'),
-    migrationsDir: TIMESCALE_MIGRATIONS_DIR ?? 'migrations',
-    migrationsTable: '__migrations',
-  } : undefined,
-  restServer: {
-    enabled: ORM_USE_REST_SERVER ?? 'true', // Whether to load restServer for automatic route setup or
-    route: ORM_REST_ROUTE ?? '/',
-  }
-}