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

package/src/dynamodb/operation-builder.ts

@@ -0,0 +1,202 @@
+/**
+ * DynamoDB operation parameter builders.
+ *
+ * Each function returns a plain-object "params" bag that can be passed
+ * directly to the corresponding DocumentClient command
+ * (PutCommand, GetCommand, UpdateCommand, DeleteCommand, ScanCommand, QueryCommand).
+ *
+ * All functions are pure — no SDK imports here; the caller wraps params
+ * in the appropriate Command class.
+ */
+
+export interface PutItemParams {
+  TableName: string;
+  Item: Record<string, unknown>;
+  ConditionExpression?: string;
+}
+
+export interface GetItemParams {
+  TableName: string;
+  Key: Record<string, unknown>;
+}
+
+export interface UpdateItemParams {
+  TableName: string;
+  Key: Record<string, unknown>;
+  UpdateExpression: string;
+  ExpressionAttributeNames: Record<string, string>;
+  ExpressionAttributeValues: Record<string, unknown>;
+  ReturnValues: string;
+}
+
+export interface DeleteItemParams {
+  TableName: string;
+  Key: Record<string, unknown>;
+}
+
+export interface ScanParams {
+  TableName: string;
+  FilterExpression?: string;
+  ExpressionAttributeNames?: Record<string, string>;
+  ExpressionAttributeValues?: Record<string, unknown>;
+  ExclusiveStartKey?: Record<string, unknown>;
+}
+
+export interface QueryParams {
+  TableName: string;
+  IndexName: string;
+  KeyConditionExpression: string;
+  ExpressionAttributeNames: Record<string, string>;
+  ExpressionAttributeValues: Record<string, unknown>;
+  ExclusiveStartKey?: Record<string, unknown>;
+}
+
+/**
+ * PutItem — optionally with a condition expression.
+ *
+ * Pass conditionExpression = 'attribute_not_exists(id)' to enforce uniqueness.
+ */
+export function buildPutItem(
+  tableName: string,
+  item: Record<string, unknown>,
+  conditionExpression?: string,
+): PutItemParams {
+  const params: PutItemParams = { TableName: tableName, Item: item };
+  if (conditionExpression) params.ConditionExpression = conditionExpression;
+  return params;
+}
+
+/**
+ * GetItem by primary key.
+ */
+export function buildGetItem(
+  tableName: string,
+  key: Record<string, unknown>,
+): GetItemParams {
+  return { TableName: tableName, Key: key };
+}
+
+/**
+ * UpdateItem with a SET expression built from the `updates` object.
+ * Only the supplied attributes are updated (diff-based call site).
+ */
+export function buildUpdateItem(
+  tableName: string,
+  key: Record<string, unknown>,
+  updates: Record<string, unknown>,
+): UpdateItemParams {
+  const names: Record<string, string> = {};
+  const values: Record<string, unknown> = {};
+  const setClauses: string[] = [];
+
+  for (const [attr, val] of Object.entries(updates)) {
+    const nameAlias = `#${attr}`;
+    const valAlias = `:${attr}`;
+    names[nameAlias] = attr;
+    values[valAlias] = val;
+    setClauses.push(`${nameAlias} = ${valAlias}`);
+  }
+
+  return {
+    TableName: tableName,
+    Key: key,
+    UpdateExpression: `SET ${setClauses.join(', ')}`,
+    ExpressionAttributeNames: names,
+    ExpressionAttributeValues: values,
+    ReturnValues: 'NONE',
+  };
+}
+
+/**
+ * DeleteItem by primary key.
+ */
+export function buildDeleteItem(
+  tableName: string,
+  key: Record<string, unknown>,
+): DeleteItemParams {
+  return { TableName: tableName, Key: key };
+}
+
+/**
+ * ScanCommand params.
+ * If conditions are supplied they are rendered as a FilterExpression using AND.
+ */
+export function buildScan(
+  tableName: string,
+  conditions?: Record<string, unknown>,
+  exclusiveStartKey?: Record<string, unknown>,
+): ScanParams {
+  const params: ScanParams = { TableName: tableName };
+
+  if (exclusiveStartKey) params.ExclusiveStartKey = exclusiveStartKey;
+
+  if (conditions && Object.keys(conditions).length > 0) {
+    const validEntries = Object.entries(conditions).filter(
+      ([, val]) => val !== undefined && val !== null,
+    );
+
+    if (validEntries.length > 0) {
+      const names: Record<string, string> = {};
+      const values: Record<string, unknown> = {};
+      const clauses: string[] = [];
+
+      for (const [attr, val] of validEntries) {
+        const nameAlias = `#${attr}`;
+        const valAlias = `:${attr}`;
+        names[nameAlias] = attr;
+        values[valAlias] = val;
+        clauses.push(`${nameAlias} = ${valAlias}`);
+      }
+
+      params.FilterExpression = clauses.join(' AND ');
+      params.ExpressionAttributeNames = names;
+      params.ExpressionAttributeValues = values;
+    }
+  }
+
+  return params;
+}
+
+/**
+ * QueryCommand params for a GSI.
+ * keyConditions must be in the form { attrName: value } and will be rendered
+ * as equality expressions joined by AND.
+ */
+export function buildQuery(
+  tableName: string,
+  indexName: string,
+  keyConditions: Record<string, unknown>,
+  exclusiveStartKey?: Record<string, unknown>,
+): QueryParams {
+  const validEntries = Object.entries(keyConditions).filter(
+    ([, val]) => val !== undefined && val !== null,
+  );
+
+  if (validEntries.length === 0) {
+    throw new Error('buildQuery: all keyCondition values are undefined/null');
+  }
+
+  const names: Record<string, string> = {};
+  const values: Record<string, unknown> = {};
+  const clauses: string[] = [];
+
+  for (const [attr, val] of validEntries) {
+    const nameAlias = `#${attr}`;
+    const valAlias = `:${attr}`;
+    names[nameAlias] = attr;
+    values[valAlias] = val;
+    clauses.push(`${nameAlias} = ${valAlias}`);
+  }
+
+  const params: QueryParams = {
+    TableName: tableName,
+    IndexName: indexName,
+    KeyConditionExpression: clauses.join(' AND '),
+    ExpressionAttributeNames: names,
+    ExpressionAttributeValues: values,
+  };
+
+  if (exclusiveStartKey) params.ExclusiveStartKey = exclusiveStartKey;
+
+  return params;
+}

package/src/dynamodb/type-map.ts

@@ -0,0 +1,54 @@
+/**
+ * Maps ORM attribute types to DynamoDB scalar attribute types.
+ * DynamoDB DocumentClient auto-marshalls JS objects, so most values
+ * are sent as their native JS types.  This map is used by the
+ * schema-introspector and startup provisioner for table/GSI creation.
+ */
+
+export type DynamoScalarType = 'S' | 'N' | 'BOOL';
+
+/**
+ * DynamoDB attribute-type string for a given ORM attr type.
+ * - string            → S
+ * - number / float    → N  (stored as Number; DocumentClient handles it)
+ * - boolean           → BOOL
+ * - date              → S  (ISO-8601 string — enables range queries)
+ * - timestamp         → N  (milliseconds since epoch)
+ * - passthrough/trim/etc → S  (safe default)
+ *
+ * For key schema declarations only `S` and `N` are valid; BOOL
+ * is legal for attributes but never for a PK/SK.
+ */
+const typeMap: Record<string, DynamoScalarType> = {
+  string: 'S',
+  number: 'N',
+  float: 'N',
+  boolean: 'BOOL',
+  date: 'S',
+  timestamp: 'N',
+  passthrough: 'S',
+  trim: 'S',
+  uppercase: 'S',
+  ceil: 'N',
+  floor: 'N',
+  round: 'N',
+};
+
+/**
+ * Returns the DynamoDB attribute type for a given ORM type string.
+ * Defaults to 'S' for any unknown/custom type.
+ */
+export function getDynamoType(attrType: string): DynamoScalarType {
+  return typeMap[attrType] ?? 'S';
+}
+
+/**
+ * Returns the DynamoDB key type ('S' | 'N') for use in KeySchema.
+ * BOOL cannot be a key attribute; anything that maps to BOOL falls back to 'S'.
+ */
+export function getDynamoKeyType(attrType: string): 'S' | 'N' {
+  const t = getDynamoType(attrType);
+  return t === 'N' ? 'N' : 'S';
+}
+
+export default typeMap;

package/src/hooks.ts

@@ -37,7 +37,21 @@ export interface HookContext {
   state?: Record<string, unknown>;
   /** Previous record state (available in update hooks). */
   oldState?: unknown;
-  /** Target record ID for single-record operations. */
+  /**
+   * Target record ID for single-record operations.
+   *
+   * SET ONLY UNDER `delete`. `_withHooks` assigns this key in the two
+   * `operation === 'delete'` branches and nowhere else, so on `get`, `list`,
+   * `create` and `update` the key is ABSENT -- not `undefined`-valued, absent.
+   * A hook rule written as `ctx.recordId === '<id>'` never fires on an update;
+   * the addressed id is in `ctx.params`. Tracked as abofs/stonyx-orm#242.
+   *
+   * @see AccessContext.recordId in ./types/orm-types.ts -- an identically-named
+   * key on an identically-shaped context object, and NOT interchangeable with
+   * this one: it is present on every route `auth()` classifies, and spells
+   * absence as `null` rather than `undefined`. They differ in coverage on four
+   * of five operations, not only in the absence spelling.
+   */
   recordId?: string | number;
   /** Response data (available in after hooks). */
   response?: unknown;

package/src/index.ts

@@ -27,6 +27,16 @@ import { count, avg, sum, min, max } from './aggregates.js';
 export { default } from './main.js';
 export { store, relationships } from './main.js';
 export type { PersistErrorDetail } from './main.js';
+export type { AccessContext, AccessFunction, AccessMethod, AccessOperation } from './types/orm-types.js'; // access() contract (#202)
+export type { LinkageFilter } from './types/orm-types.js'; // linkage verdict contract (#234)
+// The request-scoped linkage-verdict factory (#234). PUBLIC on purpose: the
+// README tells a consumer serializing a `Record` outside the REST layer to pass
+// their own resolved `linkage` option, and without an exported factory the only
+// way to follow that advice is to write a SECOND reading of `access()` in
+// consumer code -- the exact "unreviewed second authorization vocabulary" that
+// src/access-verdict.ts exists to prevent, reproduced where no reviewer sees it
+// drift. Give them the one interpreter instead of an invitation to fork it.
+export { createLinkageFilter } from './access-verdict.js';
 export { Model, View, Serializer }; // base classes
 export { attr, belongsTo, hasMany, createRecord, updateRecord }; // helpers
 export { count, avg, sum, min, max }; // aggregate helpers

package/src/main.ts

@@ -25,6 +25,7 @@ import baseTransforms from './transforms.js';
 import Store from './store.js';
 import Serializer from './serializer.js';
 import { setup } from '@stonyx/events';
+import type { AccessFunction } from './types/orm-types.js';
 
 interface OrmOptions {
   dbType?: string;
@@ -68,6 +69,53 @@ export default class Orm {
   views: Record<string, unknown> = {};
   transforms: Record<string, (value: unknown) => unknown> = { ...baseTransforms };
   warnings: Set<string> = new Set();
+
+  /**
+   * Model name -> the `access` predicate of the access class that CLAIMS that
+   * model (abofs/stonyx-orm#202).
+   *
+   * Not "that model's own predicate". One access class may claim many models
+   * -- `GlobalAccess` in this repo's fixtures declares five, and `models = '*'`
+   * claims every model in the store -- and it declares ONE `access` method, so
+   * the same function object is registered under every one of those keys.
+   * `getAccess('owner') === getAccess('animal')` is `true` there. The
+   * one-to-one guarantee below is key -> function, never function -> model,
+   * and a caller must not read a resolved predicate as being animal-specific.
+   * What makes the ANSWER model-specific is the context the caller passes and
+   * the predicate actually reading it -- see {@link Orm#getAccess}.
+   *
+   * NAMED FOR WHAT IT HOLDS. It was `accessFiles` through review, inherited
+   * from the function-local in `setup-rest-server.ts` where the values came
+   * straight out of `forEachFileImport` and "files" was defensible. The values
+   * are `AccessFunction`s, and the sibling public registries on this class
+   * (`models`, `serializers`, `views`, `transforms`) are all plural nouns of
+   * the thing held. Renamed here because #202 is the last moment it is free.
+   *
+   * Populated by `setup-rest-server.ts` at boot, from the access classes under
+   * `config.orm.paths.access`, BEFORE any route is mounted -- so it is complete
+   * and reachable before the first request can be served. The mapping is
+   * one-to-one by construction: setup-rest-server throws if two access classes
+   * claim the same model.
+   *
+   * Keys are model names as declared and stored (kebab-case, e.g.
+   * `'phone-number'`), NOT pluralised or mount-prefixed route names.
+   *
+   * WHY THIS EXISTS AS A FIELD. It used to be a function-local in
+   * setup-rest-server that was discarded when that function returned, so at
+   * request time there was no way to get from a model name to that model's
+   * predicate at all. Each `OrmRequest` held only its OWN model's predicate.
+   * That made cross-model authorization -- asking model X's predicate about a
+   * request routed to model Y -- inexpressible, which is the capability
+   * abofs/stonyx-orm#196 and abofs/stonyx-orm#207 are built on.
+   *
+   * Empty when the REST server is disabled, and PARTIAL when one access file
+   * failed to load (`setup-rest-server.ts` catches, warns and assigns whatever
+   * it had). So a missing key does NOT mean the model has no access class.
+   * Prefer {@link Orm#getAccess} over indexing this directly -- it is guarded
+   * against the prototype chain and this is not.
+   */
+  accessFunctions: Record<string, AccessFunction> = {};
+
   options!: OrmOptions;
   sqlDb?: SqlDb;
   db?: OrmDB | SqlDb;
@@ -90,6 +138,11 @@ export default class Orm {
   }
 
   async init(): Promise<void> {
+    // Self-register so log.db works even when @stonyx/orm is in the
+    // consumer's `dependencies` (stonyx loader only merges devDependencies).
+    const { logColor = 'white', logMethod = 'db' } = config.orm;
+    log.defineType(logMethod, logColor);
+
     const { paths, restServer } = config.orm;
 
     const promises: Promise<unknown>[] = ['Model', 'Serializer', 'Transform'].map(type => {
@@ -159,6 +212,11 @@ export default class Orm {
       this.sqlDb = new MysqlDB() as SqlDb;
       this.db = this.sqlDb;
       promises.push(this.sqlDb.init());
+    } else if (config.orm.dynamodb) {
+      const { default: DynamoDBDB } = await import('./dynamodb/dynamodb-db.js');
+      this.sqlDb = new DynamoDBDB() as SqlDb;
+      this.db = this.sqlDb;
+      promises.push(this.sqlDb.init());
     } else if (this.options.dbType !== 'none') {
       const db = new DB();
       this.db = db;
@@ -185,6 +243,81 @@ export default class Orm {
     Orm.initialized = true;
   }
 
+  /**
+   * Resolve the `access` predicate registered for a model name
+   * (abofs/stonyx-orm#202).
+   *
+   * This is the supported way to reach another model's predicate while
+   * servicing a request routed to a different model. Call it with the model
+   * name and invoke the result with the live request and an explicit context
+   * naming THAT model:
+   *
+   * ```js
+   * const predicate = Orm.instance.getAccess('animal');
+   * if (!predicate) return deny;
+   * const verdict = predicate(request, { model: 'animal', operation: 'read' });
+   * ```
+   *
+   * WHAT IT RESOLVES. The predicate of the access CLASS that claims the model,
+   * which is not necessarily specific to it: one class may claim many models
+   * and declares one `access` method, so
+   * `getAccess('owner') === getAccess('animal')` is `true` against this repo's
+   * fixture. See {@link Orm#accessFunctions}.
+   *
+   * `undefined` means NO PREDICATE COULD BE RESOLVED for that name. That
+   * includes a model whose access class failed to LOAD -- `setup-rest-server`
+   * catches, warns and publishes the partial map -- so it is not the same claim
+   * as "this model is unrestricted". Treat it as DENY, the same way
+   * `AccessContext.operation === undefined` is treated.
+   *
+   * PASSING THE CONTEXT MAKES A MODEL-CORRECT ANSWER POSSIBLE. It does not, on
+   * its own, make the answer model-correct: the resolved predicate has to READ
+   * the context. Measured against this repo's shipped access class on a request
+   * express dispatched to `GET /owners/angela`, asked about ANIMALS:
+   *
+   * ```
+   * getAccess('animal')(ownersRequest, { model: 'animal', operation: 'read' })
+   *   ->  record => record.id !== 'angela' && record.id !== 'restricted'
+   * ```
+   *
+   * The OWNERS filter, which returns `true` for animal 21 -- the record hidden
+   * on every animal surface. Under a mount that predicate recognises neither
+   * way it falls through to `['read', 'create', 'update', 'delete']`, a full
+   * CRUD grant. Either way: context supplied, answer not the animal answer,
+   * wrong in the GRANTING direction, because that predicate is arity-1 and
+   * identifies its collection from the request. AC9 asserts the first case on a
+   * live dispatch.
+   *
+   * Every predicate in this repo and in every consumer tree is arity-1 today,
+   * and there is no supported way for the caller to tell which kind it got; the
+   * boot-time arity warning that would surface it is abofs/stonyx-orm#213. Pass
+   * the context, and do not treat a resolved predicate's answer as
+   * model-specific until that predicate reads it.
+   *
+   * OWN PROPERTIES ONLY. A bare `this.accessFunctions[modelName]` walks the
+   * prototype chain, so `getAccess('constructor')` resolved `Object` and
+   * `getAccess('toString')` resolved `Object.prototype.toString` -- both
+   * callable, and the documented `predicate?.(request, ctx)` pattern then
+   * returned a TRUTHY value (`Object(request)` is the request), bypassing the
+   * `undefined`-means-deny contract entirely. Nothing in the ORM calls
+   * `getAccess` yet, so it was not exploitable as shipped -- but #207 takes the
+   * model name from the REQUEST BODY (`data.relationships.<key>.data.type`),
+   * which would have made a one-field body an authorization bypass. Guarded
+   * here at the read point rather than by constructing the map with a null
+   * prototype, because the field is public and reassignable and the guard has
+   * to hold whatever object it is holding.
+   *
+   * @param modelName - Model name as declared and stored (kebab-case).
+   * @returns The predicate, or `undefined` when no predicate could be resolved
+   *   for that name. `undefined` is NOT "this model is unrestricted" -- see the
+   *   note above. Treat it as deny.
+   */
+  getAccess(modelName: string): AccessFunction | undefined {
+    if (!Object.hasOwn(this.accessFunctions, modelName)) return undefined;
+
+    return this.accessFunctions[modelName];
+  }
+
   async startup(): Promise<void> {
     if (this.sqlDb) await this.sqlDb.startup();
   }