@stonyx/orm 0.3.2-beta.235 → 0.3.2-beta.236

package/README.md

@@ -40,6 +40,12 @@ All properties prefixed with `__` (`__data`, `__relationships`, `__model`, `__se
 npm install @stonyx/orm
 ````
 
+That is the whole install for an ORM-only app. The database drivers and
+`@stonyx/rest-server` are **optional peer dependencies**: a default install does
+not put them on disk, and none of them is loaded unless your configuration asks
+for it. Add only the ones you actually use — see
+[Optional peer dependencies](#optional-peer-dependencies).
+
 ## Usage example
 
 This module is part of the **Stonyx framework**. To use it, first configure the `restServer` key in your `environment.js` file:
@@ -106,7 +112,9 @@ export default {
       tablePrefix: DYNAMODB_TABLE_PREFIX,   // optional table name prefix
     } : undefined,
     restServer: {
-      enabled: ORM_USE_REST_SERVER ?? 'true',
+      // 'true' requires @stonyx/rest-server to be installed — see
+      // "Optional peer dependencies" below.
+      enabled: ORM_USE_REST_SERVER ?? 'false',
       route: ORM_REST_ROUTE ?? '/'
     }
   }
@@ -127,6 +135,46 @@ stonyx serve
 
 For further framework instructions, see the [Stonyx repository](https://github.com/abofs/stonyx).
 
+## Optional peer dependencies
+
+`@stonyx/orm` boots with **none** of its optional peers installed. Each one is
+imported lazily, and only when your configuration selects it:
+
+| Configuration | Package you must install |
+|---|---|
+| `orm.restServer.enabled: 'true'` | `@stonyx/rest-server` |
+| `orm.postgres` or `orm.timescale` | `pg` |
+| `orm.mysql` | `mysql2` |
+| `orm.dynamodb` | `@aws-sdk/client-dynamodb`, `@aws-sdk/lib-dynamodb` |
+
+If a configuration key selects one that is not on disk, the failure surfaces
+from `Orm.init()` while the framework boots:
+
+```
+Cannot find package '@stonyx/rest-server' imported from .../@stonyx/orm/dist/orm-request.js
+```
+
+**ORM-only, no REST server.** This is the shape the `environment.js` above is
+written for: keep `orm.restServer.enabled` at `'false'` and install nothing
+beyond `@stonyx/orm`. Models, relationships, serializers, transforms and hooks
+work unchanged; only the generated REST routes are absent.
+
+> **The module's own default is the other way round.** The `config/environment.js`
+> that ships inside `@stonyx/orm` defaults `restServer.enabled` to `'true'`, so
+> an app that omits the `restServer` key *entirely* gets REST switched on and
+> needs `@stonyx/rest-server` installed. Set the key explicitly, whichever way
+> you want it.
+
+**Turning REST on.**
+
+```bash
+npm install @stonyx/rest-server
+ORM_USE_REST_SERVER=true stonyx serve
+```
+
+See [REST Server Integration](#rest-server-integration) for access classes and
+route configuration.
+
 ## Models
 
 Define a model with attributes and relationships:
@@ -916,7 +964,9 @@ test('validation hook rejects negative age', async () => {
 
 ## Project Structure
 
-For a full architectural reference, see [project-structure.md](project-structure.md).
+For a full architectural reference, see
+[docs/project-structure.md](https://github.com/abofs/stonyx-orm/blob/dev/docs/project-structure.md).
+That file is repo-only — it is not in the published tarball, so the link is absolute.
 
 ## License
 

package/dist/main.js

@@ -19,7 +19,6 @@ import log from 'stonyx/log';
 import { forEachFileImport } from '@stonyx/utils/file';
 import { kebabCaseToPascalCase, pluralize } from '@stonyx/utils/string';
 import { registerPluralName } from './plural-registry.js';
-import setupRestServer from './setup-rest-server.js';
 import baseTransforms from './transforms.js';
 import Store from './store.js';
 import Serializer from './serializer.js';
@@ -131,6 +130,25 @@ export default class Orm {
             promises.push(db.init());
         }
         if (restServer.enabled === 'true') {
+            // MUST stay dynamic. setup-rest-server.js names the optional
+            // '@stonyx/rest-server' peer in its own static graph — directly, and
+            // through orm-request.ts / meta-request.ts, which import `Request` at
+            // module scope because they extend it (correctly: an `extends` base
+            // class cannot be awaited). Node links a module's entire static graph
+            // before evaluating any of it, so a static import here puts that
+            // specifier on the entry graph and `import('@stonyx/orm')` throws
+            // ERR_MODULE_NOT_FOUND for an ORM-only consumer that never installed the
+            // optional peer.
+            //
+            // NOT the same reason the SQL/DynamoDB drivers above are lazy: those
+            // modules carry no static peer specifier that survives to `dist/`
+            // (postgres-db.ts:15 and mysql-db.ts:17 are `import type`, erased by
+            // tsc), so the `await import()` there is not what isolates pg / mysql2 /
+            // @aws-sdk — that happens one layer down, in src/*/connection.ts (and
+            // src/dynamodb/dynamodb-db.ts).
+            // setup-rest-server.js is the only dist module whose laziness is
+            // load-bearing for peer resolution. (#280)
+            const { default: setupRestServer } = await import('./setup-rest-server.js');
             promises.push(setupRestServer(restServer.route, paths.access, restServer.metaRoute));
         }
         // Wire up memory resolver so store.find() can check model memory flags

package/package.json

@@ -4,7 +4,7 @@
     "stonyx-async",
     "stonyx-module"
   ],
-  "version": "0.3.2-beta.235",
+  "version": "0.3.2-beta.236",
   "description": "",
   "main": "dist/index.js",
   "type": "module",

package/src/main.ts

@@ -20,7 +20,6 @@ import log from 'stonyx/log';
 import { forEachFileImport } from '@stonyx/utils/file';
 import { kebabCaseToPascalCase, pluralize } from '@stonyx/utils/string';
 import { registerPluralName } from './plural-registry.js';
-import setupRestServer from './setup-rest-server.js';
 import baseTransforms from './transforms.js';
 import Store from './store.js';
 import Serializer from './serializer.js';
@@ -177,6 +176,25 @@ export default class Orm {
     }
 
     if (restServer.enabled === 'true') {
+      // MUST stay dynamic. setup-rest-server.js names the optional
+      // '@stonyx/rest-server' peer in its own static graph — directly, and
+      // through orm-request.ts / meta-request.ts, which import `Request` at
+      // module scope because they extend it (correctly: an `extends` base
+      // class cannot be awaited). Node links a module's entire static graph
+      // before evaluating any of it, so a static import here puts that
+      // specifier on the entry graph and `import('@stonyx/orm')` throws
+      // ERR_MODULE_NOT_FOUND for an ORM-only consumer that never installed the
+      // optional peer.
+      //
+      // NOT the same reason the SQL/DynamoDB drivers above are lazy: those
+      // modules carry no static peer specifier that survives to `dist/`
+      // (postgres-db.ts:15 and mysql-db.ts:17 are `import type`, erased by
+      // tsc), so the `await import()` there is not what isolates pg / mysql2 /
+      // @aws-sdk — that happens one layer down, in src/*/connection.ts (and
+      // src/dynamodb/dynamodb-db.ts).
+      // setup-rest-server.js is the only dist module whose laziness is
+      // load-bearing for peer resolution. (#280)
+      const { default: setupRestServer } = await import('./setup-rest-server.js');
       promises.push(setupRestServer(restServer.route, paths.access, restServer.metaRoute));
     }