@stonyx/orm 0.3.2-alpha.57 → 0.3.2-alpha.58

package/README.md

@@ -463,7 +463,7 @@ const verdict = predicate?.(request, { model: 'animal', operation: 'read' });
 ```
 
 `Orm.instance.getAccess(modelName)` returns the predicate, or `undefined` when
-that model has no access class. The raw map is `Orm.instance.accessFiles`, keyed
+that model has no access class. The raw map is `Orm.instance.accessFunctions`, keyed
 by model name; prefer `getAccess()`.
 
 Passing the context explicitly is what makes the answer **model-correct**. A

package/dist/main.d.ts

@@ -34,7 +34,25 @@ export default class Orm {
     transforms: Record<string, (value: unknown) => unknown>;
     warnings: Set<string>;
     /**
-     * Model name -> that model's `access` predicate (abofs/stonyx-orm#202).
+     * 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
@@ -53,10 +71,13 @@ export default class Orm {
      * 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, or when no access configuration
-     * could be loaded. Prefer {@link Orm#getAccess} over indexing this directly.
+     * 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.
      */
-    accessFiles: Record<string, AccessFunction>;
+    accessFunctions: Record<string, AccessFunction>;
     options: OrmOptions;
     sqlDb?: SqlDb;
     db?: OrmDB | SqlDb;
@@ -81,7 +102,7 @@ export default class Orm {
      * collection the request is ADDRESSED TO -- owners -- while being asked about
      * animals, and per #202's thesis it answers wrong in the granting direction.
      *
-     * OWN PROPERTIES ONLY. A bare `this.accessFiles[modelName]` walks the
+     * 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

package/dist/main.js

@@ -39,7 +39,25 @@ export default class Orm {
     transforms = { ...baseTransforms };
     warnings = new Set();
     /**
-     * Model name -> that model's `access` predicate (abofs/stonyx-orm#202).
+     * 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
@@ -58,10 +76,13 @@ export default class Orm {
      * 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, or when no access configuration
-     * could be loaded. Prefer {@link Orm#getAccess} over indexing this directly.
+     * 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.
      */
-    accessFiles = {};
+    accessFunctions = {};
     options;
     sqlDb;
     db;
@@ -187,7 +208,7 @@ export default class Orm {
      * collection the request is ADDRESSED TO -- owners -- while being asked about
      * animals, and per #202's thesis it answers wrong in the granting direction.
      *
-     * OWN PROPERTIES ONLY. A bare `this.accessFiles[modelName]` walks the
+     * 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
@@ -206,9 +227,9 @@ export default class Orm {
      *   note above. Treat it as deny.
      */
     getAccess(modelName) {
-        if (!Object.hasOwn(this.accessFiles, modelName))
+        if (!Object.hasOwn(this.accessFunctions, modelName))
             return undefined;
-        return this.accessFiles[modelName];
+        return this.accessFunctions[modelName];
     }
     async startup() {
         if (this.sqlDb)

package/dist/setup-rest-server.js

@@ -8,7 +8,7 @@ import { dbKey } from './db.js';
 import { getPluralName } from './plural-registry.js';
 import log from 'stonyx/log';
 export default async function (route, accessPath, metaRoute) {
-    const accessFiles = {};
+    const accessFunctions = {};
     try {
         await forEachFileImport(accessPath, (accessClass) => {
             const accessInstance = new accessClass();
@@ -25,9 +25,9 @@ export default async function (route, accessPath, metaRoute) {
                     continue;
                 if (!store.data.has(model))
                     throw new Error(`Unable to define access for Invalid Model "${model}". Model does not exist`);
-                if (accessFiles[model])
+                if (accessFunctions[model])
                     throw new Error(`Access for model "${model}" has already been defined by another access class.`);
-                accessFiles[model] = accessInstance.access;
+                accessFunctions[model] = accessInstance.access;
             }
         });
     }
@@ -38,7 +38,7 @@ export default async function (route, accessPath, metaRoute) {
     // -------------------------------------------------------------------------
     // #202 -- the registry has to survive this function.
     //
-    // `accessFiles` used to be a function-local that was discarded at the return
+    // `accessFunctions` used to be a function-local that was discarded at the return
     // below, so the only thing that ever saw it was the mount loop. Each mounted
     // OrmRequest then held its OWN model's predicate and nothing held the map, so
     // at request time there was no route from a model NAME to that model's
@@ -56,12 +56,12 @@ export default async function (route, accessPath, metaRoute) {
     // set of predicates that is actually enforcing. A guard here that skipped the
     // assignment would let the registry go silently missing, which is precisely
     // the failure #202's AC8 exists to catch.
-    Orm.instance.accessFiles = accessFiles;
+    Orm.instance.accessFunctions = accessFunctions;
     await waitForModule('rest-server');
     // Remove "/" prefix and name mount point accordingly
     const name = route === '/' ? 'index' : (route[0] === '/' ? route.slice(1) : route);
     // Configure endpoints for models and views with access configuration
-    for (const [model, access] of Object.entries(accessFiles)) {
+    for (const [model, access] of Object.entries(accessFunctions)) {
         const pluralizedModel = getPluralName(model);
         const modelName = name === 'index' ? pluralizedModel : `${name}/${pluralizedModel}`;
         RestServer.instance.mountRoute(OrmRequest, { name: modelName, options: { model, access } });

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-alpha.57",
+  "version": "0.3.2-alpha.58",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

package/src/main.ts

@@ -71,7 +71,25 @@ export default class Orm {
   warnings: Set<string> = new Set();
 
   /**
-   * Model name -> that model's `access` predicate (abofs/stonyx-orm#202).
+   * 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
@@ -90,10 +108,13 @@ export default class Orm {
    * 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, or when no access configuration
-   * could be loaded. Prefer {@link Orm#getAccess} over indexing this directly.
+   * 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.
    */
-  accessFiles: Record<string, AccessFunction> = {};
+  accessFunctions: Record<string, AccessFunction> = {};
 
   options!: OrmOptions;
   sqlDb?: SqlDb;
@@ -240,7 +261,7 @@ export default class Orm {
    * collection the request is ADDRESSED TO -- owners -- while being asked about
    * animals, and per #202's thesis it answers wrong in the granting direction.
    *
-   * OWN PROPERTIES ONLY. A bare `this.accessFiles[modelName]` walks the
+   * 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
@@ -259,9 +280,9 @@ export default class Orm {
    *   note above. Treat it as deny.
    */
   getAccess(modelName: string): AccessFunction | undefined {
-    if (!Object.hasOwn(this.accessFiles, modelName)) return undefined;
+    if (!Object.hasOwn(this.accessFunctions, modelName)) return undefined;
 
-    return this.accessFiles[modelName];
+    return this.accessFunctions[modelName];
   }
 
   async startup(): Promise<void> {

package/src/setup-rest-server.ts

@@ -20,7 +20,7 @@ interface AccessInstance {
 }
 
 export default async function(route: string, accessPath: string, metaRoute: boolean): Promise<void> {
-  const accessFiles: Record<string, AccessFunction> = {};
+  const accessFunctions: Record<string, AccessFunction> = {};
 
   try {
     await forEachFileImport(accessPath, (accessClass: unknown) => {
@@ -37,9 +37,9 @@ export default async function(route: string, accessPath: string, metaRoute: bool
       for (const model of models === '*' ? availableModels : models) {
         if (model === dbKey) continue;
         if (!store.data.has(model)) throw new Error(`Unable to define access for Invalid Model "${model}". Model does not exist`);
-        if (accessFiles![model]) throw new Error(`Access for model "${model}" has already been defined by another access class.`);
+        if (accessFunctions![model]) throw new Error(`Access for model "${model}" has already been defined by another access class.`);
 
-        accessFiles![model] = accessInstance.access;
+        accessFunctions![model] = accessInstance.access;
       }
     });
   } catch (error) {
@@ -50,7 +50,7 @@ export default async function(route: string, accessPath: string, metaRoute: bool
   // -------------------------------------------------------------------------
   // #202 -- the registry has to survive this function.
   //
-  // `accessFiles` used to be a function-local that was discarded at the return
+  // `accessFunctions` used to be a function-local that was discarded at the return
   // below, so the only thing that ever saw it was the mount loop. Each mounted
   // OrmRequest then held its OWN model's predicate and nothing held the map, so
   // at request time there was no route from a model NAME to that model's
@@ -68,7 +68,7 @@ export default async function(route: string, accessPath: string, metaRoute: bool
   // set of predicates that is actually enforcing. A guard here that skipped the
   // assignment would let the registry go silently missing, which is precisely
   // the failure #202's AC8 exists to catch.
-  Orm.instance.accessFiles = accessFiles;
+  Orm.instance.accessFunctions = accessFunctions;
 
   await waitForModule('rest-server');
 
@@ -76,7 +76,7 @@ export default async function(route: string, accessPath: string, metaRoute: bool
   const name = route === '/' ? 'index' : (route[0] === '/' ? route.slice(1) : route);
 
   // Configure endpoints for models and views with access configuration
-  for (const [model, access] of Object.entries(accessFiles!)) {
+  for (const [model, access] of Object.entries(accessFunctions!)) {
     const pluralizedModel = getPluralName(model);
     const modelName = name === 'index' ? pluralizedModel : `${name}/${pluralizedModel}`;
     RestServer.instance.mountRoute(OrmRequest, { name: modelName, options: { model, access } });