@_linked/server 2.18.0 → 2.20.0

package/lib/esm/shapes/index.d.ts

@@ -1,4 +1,4 @@
-import '../ontologies/lincd-server.register.js';
+import '../ontologies/server.register.js';
 import './LinkedServer.js';
 import './LincdAPI.js';
 import './LincdWebApp.js';

package/lib/esm/shapes/index.js

@@ -1,7 +1,7 @@
 // Registers every shape this package defines. Side-effect imports only: a
 // consumer (or the host app) can load this one module to get the full set of
 // shapes registered, without pulling in components, providers or other exports.
-import '../ontologies/lincd-server.register.js';
+import '../ontologies/server.register.js';
 import './LinkedServer.js';
 import './LincdAPI.js';
 import './LincdWebApp.js';

package/lib/esm/shapes/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/shapes/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,6EAA6E;AAC7E,gFAAgF;AAChF,OAAO,wCAAwC,CAAC;AAEhD,OAAO,mBAAmB,CAAC;AAC3B,OAAO,eAAe,CAAC;AACvB,OAAO,kBAAkB,CAAC","sourcesContent":["// Registers every shape this package defines. Side-effect imports only: a\n// consumer (or the host app) can load this one module to get the full set of\n// shapes registered, without pulling in components, providers or other exports.\nimport '../ontologies/lincd-server.register.js';\n\nimport './LinkedServer.js';\nimport './LincdAPI.js';\nimport './LincdWebApp.js';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/shapes/index.ts"],"names":[],"mappings":"AAAA,0EAA0E;AAC1E,6EAA6E;AAC7E,gFAAgF;AAChF,OAAO,kCAAkC,CAAC;AAE1C,OAAO,mBAAmB,CAAC;AAC3B,OAAO,eAAe,CAAC;AACvB,OAAO,kBAAkB,CAAC","sourcesContent":["// Registers every shape this package defines. Side-effect imports only: a\n// consumer (or the host app) can load this one module to get the full set of\n// shapes registered, without pulling in components, providers or other exports.\nimport '../ontologies/server.register.js';\n\nimport './LinkedServer.js';\nimport './LincdAPI.js';\nimport './LincdWebApp.js';\n"]}

package/lib/esm/utils/fatalError.d.ts

@@ -0,0 +1,36 @@
+/**
+ * The fatal-error contract between providers and the server's boot.
+ *
+ * The server isolates provider failures: a provider constructor, a backend
+ * module load or a boot hook that throws is logged with the package name and
+ * boot carries on without that provider. That is right for a bug, and wrong
+ * for a provider that has decided the app must not serve at all — auth with
+ * no signing secret in production, say. Serving anyway looks healthy and
+ * fails every request that needs it.
+ *
+ * So: an error with an OWN property `fatal` set to `true` is not swallowed
+ * when it is thrown at boot. The server logs it, `start()` rejects with it,
+ * and the process exits non-zero. Any error object qualifies — a provider
+ * does not need to depend on this package to use the contract:
+ *
+ *   throw Object.assign(new Error('JWT_SECRET is not set'), {fatal: true});
+ *
+ * or, with this package available:
+ *
+ *   throw new FatalStartupError('JWT_SECRET is not set');
+ *
+ * Thrown after boot (a per-request hook, a lazy load on a later /call, an
+ * HMR reload) it is logged as fatal but does not stop a running server.
+ */
+export interface FatalError extends Error {
+    fatal: true;
+}
+/** An error that refuses to let the server start. See {@link FatalError}. */
+export declare class FatalStartupError extends Error implements FatalError {
+    fatal: true;
+    constructor(message: string, options?: {
+        cause?: unknown;
+    });
+}
+/** True for an error that carries the fatal contract: own `fatal === true`. */
+export declare function isFatalError(err: unknown): err is FatalError;

package/lib/esm/utils/fatalError.js

@@ -0,0 +1,22 @@
+/** An error that refuses to let the server start. See {@link FatalError}. */
+export class FatalStartupError extends Error {
+    constructor(message, options) {
+        super(message);
+        // `cause` by hand: the ES2022 Error(message, options) signature is not in
+        // this package's lib target.
+        if (options && 'cause' in options)
+            this.cause = options.cause;
+        this.name = 'FatalStartupError';
+        // Assigned, not declared with an initializer, so it is an own property
+        // whatever the class-field emit.
+        this.fatal = true;
+    }
+}
+/** True for an error that carries the fatal contract: own `fatal === true`. */
+export function isFatalError(err) {
+    return (!!err &&
+        typeof err === 'object' &&
+        Object.prototype.hasOwnProperty.call(err, 'fatal') &&
+        err.fatal === true);
+}
+//# sourceMappingURL=fatalError.js.map

package/lib/esm/utils/fatalError.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"fatalError.js","sourceRoot":"","sources":["../../../src/utils/fatalError.ts"],"names":[],"mappings":"AA4BA,6EAA6E;AAC7E,MAAM,OAAO,iBAAkB,SAAQ,KAAK;IAE1C,YAAY,OAAe,EAAE,OAA6B;QACxD,KAAK,CAAC,OAAO,CAAC,CAAC;QACf,0EAA0E;QAC1E,6BAA6B;QAC7B,IAAI,OAAO,IAAI,OAAO,IAAI,OAAO;YAAG,IAAY,CAAC,KAAK,GAAG,OAAO,CAAC,KAAK,CAAC;QACvE,IAAI,CAAC,IAAI,GAAG,mBAAmB,CAAC;QAChC,uEAAuE;QACvE,iCAAiC;QACjC,IAAI,CAAC,KAAK,GAAG,IAAI,CAAC;IACpB,CAAC;CACF;AAED,+EAA+E;AAC/E,MAAM,UAAU,YAAY,CAAC,GAAY;IACvC,OAAO,CACL,CAAC,CAAC,GAAG;QACL,OAAO,GAAG,KAAK,QAAQ;QACvB,MAAM,CAAC,SAAS,CAAC,cAAc,CAAC,IAAI,CAAC,GAAG,EAAE,OAAO,CAAC;QACjD,GAAW,CAAC,KAAK,KAAK,IAAI,CAC5B,CAAC;AACJ,CAAC","sourcesContent":["/**\n * The fatal-error contract between providers and the server's boot.\n *\n * The server isolates provider failures: a provider constructor, a backend\n * module load or a boot hook that throws is logged with the package name and\n * boot carries on without that provider. That is right for a bug, and wrong\n * for a provider that has decided the app must not serve at all — auth with\n * no signing secret in production, say. Serving anyway looks healthy and\n * fails every request that needs it.\n *\n * So: an error with an OWN property `fatal` set to `true` is not swallowed\n * when it is thrown at boot. The server logs it, `start()` rejects with it,\n * and the process exits non-zero. Any error object qualifies — a provider\n * does not need to depend on this package to use the contract:\n *\n *   throw Object.assign(new Error('JWT_SECRET is not set'), {fatal: true});\n *\n * or, with this package available:\n *\n *   throw new FatalStartupError('JWT_SECRET is not set');\n *\n * Thrown after boot (a per-request hook, a lazy load on a later /call, an\n * HMR reload) it is logged as fatal but does not stop a running server.\n */\nexport interface FatalError extends Error {\n  fatal: true;\n}\n\n/** An error that refuses to let the server start. See {@link FatalError}. */\nexport class FatalStartupError extends Error implements FatalError {\n  fatal: true;\n  constructor(message: string, options?: { cause?: unknown }) {\n    super(message);\n    // `cause` by hand: the ES2022 Error(message, options) signature is not in\n    // this package's lib target.\n    if (options && 'cause' in options) (this as any).cause = options.cause;\n    this.name = 'FatalStartupError';\n    // Assigned, not declared with an initializer, so it is an own property\n    // whatever the class-field emit.\n    this.fatal = true;\n  }\n}\n\n/** True for an error that carries the fatal contract: own `fatal === true`. */\nexport function isFatalError(err: unknown): err is FatalError {\n  return (\n    !!err &&\n    typeof err === 'object' &&\n    Object.prototype.hasOwnProperty.call(err, 'fatal') &&\n    (err as any).fatal === true\n  );\n}\n"]}

package/package.json

@@ -10,7 +10,7 @@
     "type": "git",
     "url": "git+https://github.com/linked-fw/server.git"
   },
-  "version": "2.18.0",
+  "version": "2.20.0",
   "packageManager": "npm@11.20.0",
   "linkedPackage": true,
   "type": "module",

package/readme.md

@@ -21,6 +21,7 @@ If you want to further adjust the functionality of LincdServer yourself, either
   - [Error semantics](#error-semantics)
 - [API-only servers (`server.apiOnly`)](#api-only-servers-serverapionly)
 - [Provider lifecycle and HMR](#provider-lifecycle-and-hmr)
+  - [When a provider throws, and refusing to start](#when-a-provider-throws-and-refusing-to-start)
   - [When to implement `dispose()`](#when-to-implement-dispose)
   - [Route tracking helpers](#route-tracking-helpers)
   - [Examples](#examples)
@@ -257,6 +258,25 @@ Every provider — generic (`BackendProvider`) or shape-scoped (`ShapeProvider`)
 
 The dispose step is what makes hot-reload safe. Without it, anything the constructor or boot hooks registered — Express routes, middleware, listeners, timers, global-singleton mutations — would accumulate every time the source file changed. The framework calls `dispose()` on the OLD provider before replacing it with a freshly-instantiated one.
 
+### When a provider throws, and refusing to start
+
+A provider that throws is isolated: a failing constructor, a backend module that throws when it loads, or a boot hook that throws or rejects is logged with the package and hook name (`[linked] <pkg> <hook> failed: …`), and the rest of the app still starts without it. Per-request hooks (`initRequest`, `supplyDataForRequest`) are isolated the same way — the request is served with the other providers' data.
+
+Sometimes a provider must not let the app serve at all — auth with no signing secret in production, say, where serving anyway looks healthy and fails every sign-in. For that, throw an error with an **own property `fatal` set to `true`**:
+
+```ts
+// No dependency on @_linked/server needed:
+throw Object.assign(new Error('JWT_SECRET is not set'), {fatal: true});
+
+// or, with the helper:
+import {FatalStartupError} from '@_linked/server/utils/fatalError';
+throw new FatalStartupError('JWT_SECRET is not set');
+```
+
+Thrown while the server boots — from a provider constructor, a backend module's top level, or `setupBeforeControllers` / `setupBeforeCatchAllControllers` / `setupAfterControllers` — it is logged as `[linked] <pkg> <hook>: fatal error, refusing to start: <message>`, `start()` (and `initOnly()`) rejects with it before the server listens, and the process exits with code 1. The exit code is set immediately; because a rejected `start()` alone does not end a process that still has a Vite dev server, a store connection or a timer open, the server also calls `process.exit(1)` a second later (an embedder can override `exitAfterFatalStartupError`). `isFatalError(err)` checks the contract.
+
+Thrown after boot — from a per-request hook, a backend loaded lazily by a later `/call`, or an HMR reload — the error is logged as fatal (`… fatal error after start, server keeps running: …`) and contained like any other: one provider does not take down a server that is already serving. A provider that must refuse should therefore decide at construction or in a boot hook.
+
 ### When to implement `dispose()`
 
 Implement `dispose()` when your provider does any of the following at construction or boot: