@_linked/server 2.24.11 → 3.0.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @\_linked/server
 
+## 3.0.0
+
+### Major Changes
+
+- [#179](https://github.com/linked-fw/server/pull/179) [`0a032fb`](https://github.com/linked-fw/server/commit/0a032fbc830fd001ccb27330072090019259c206) Thanks [@flyon](https://github.com/flyon)! - `BackendAPIStore` is renamed `RemoteDataset` and gains a `url`/`token` form for a remote data server; `GatewayStore` is removed; new public `ping` method.
+
+  Migration:
+
+  - **`BackendAPIStore` users:** replace the import path `@_linked/server/shapes/quadstores/BackendAPIStore` with `@_linked/server/shapes/quadstores/RemoteDataset` and the class name `BackendAPIStore` with `RemoteDataset` (in code and in the `store` of `linked.{frontend,backend}.datasets.json`). Without `url` the behaviour is unchanged; there is no alias.
+  - **`GatewayStore` users:** point `RemoteDataset` at the server's `/call` base instead: config `{ "url": "<base>", "token": "<bearer token>" }` (was `{ endpoint, credential }`). It posts `{"args": [query.toJSON()]}` to `{url}/call/@_linked/server/<method>` with `Authorization: Bearer <token>`; the `{v, op, query}` envelope, `/query` and `/health` routes and the `fetch` config override are gone.
+  - **Config:** `RemoteDatasetConfig` is `{ url?, token?, name?, id? }`. A `url` that is present but empty never falls back to the no-url form.
+  - **`init()`:** with `url`, it posts to `{url}/call/@_linked/server/ping` (memoized on success) and throws a typed error. Await it before registering the store.
+  - **Errors:** `GatewayStoreError` / `GatewayUnreachableError` are replaced by `RemoteDatasetError` (`url`, `status`, optional `code`) and its subclasses `RemoteDatasetUnreachableError` (no answer, empty url, or nothing at the url speaks the wire) and `RemoteDatasetUnauthorizedError` (401 or 403).
+  - **`ping`:** `POST /call/@_linked/server/ping` is a new `public` method that answers `{ "ok": true }`.
+
+## 2.25.0
+
+### Minor Changes
+
+- [#177](https://github.com/linked-fw/server/pull/177) [`781e5d0`](https://github.com/linked-fw/server/commit/781e5d0f41a8fa7a2e0984f9740003968511c759) Thanks [@flyon](https://github.com/flyon)! - GatewayStore: an IDataset that forwards Linked Queries to a gateway. Exported at `@_linked/server/shapes/quadstores/GatewayStore` so an app can select it from `linked.backend.datasets.json`; it posts each query as DSL-JSON with a bearer credential and throws `GatewayUnreachableError` from `init()` when the gateway does not answer.
+
 ## 2.24.11
 
 ### Patch Changes

package/lib/esm/backend.d.ts

@@ -1,6 +1,14 @@
 import { BackendProvider } from '@_linked/server-utils/utils/BackendProvider';
 export default class LincdServerBackendProvider extends BackendProvider {
     setupBeforeControllers(): Promise<void>;
+    /**
+     * Reachability check for a `RemoteDataset` pointed at this server: reads nothing, changes
+     * nothing. A plain linked server has no token concept, so it always answers `{ok: true}`;
+     * a host that serves the wire with tokens answers 401 for a refused one.
+     */
+    ping(): Promise<{
+        ok: true;
+    }>;
     selectQuery(json: any): Promise<unknown>;
     askQuery(json: any): Promise<boolean>;
     updateQuery(json: any): Promise<unknown>;

package/lib/esm/backend.js

@@ -30,22 +30,25 @@ export default class LincdServerBackendProvider extends BackendProvider {
             });
         }
     }
-    // ── BackendAPIStore query execution ──────────────────────────────────────
-    //
-    // These answer the frontend `BackendAPIStore`, which calls
-    // `Server.call(packageName, {method}, json)` — the PACKAGE form, so the request
-    // arrives here on the generic provider rather than through Shape resolution.
+    /**
+     * Reachability check for a `RemoteDataset` pointed at this server: reads nothing, changes
+     * nothing. A plain linked server has no token concept, so it always answers `{ok: true}`;
+     * a host that serves the wire with tokens answers 401 for a refused one.
+     */
+    async ping() {
+        return { ok: true };
+    }
+    // ── Generic query execution ──────────────────────────────────────────────
     //
-    // They used to live on `BackendAPIStoreProvider`, a `ShapeProvider`, whose methods
-    // took the store as a first argument and never read it. Reaching that provider meant
-    // the transport had to carry a `shapeURI` and an `instanceNode`, and the server had to
-    // rebuild the store with `new (providerShapeClass)({id})` — instantiating a Shape only
-    // to discard it. Addressing by package removes all of that.
+    // These answer `RemoteDataset`: a browser's store calls
+    // `Server.call(packageName, {method}, json)` (the PACKAGE form), and a remote app's store
+    // posts the same `{args}` body to `{url}/call/@_linked/server/<method>`. Either way the
+    // request arrives here on the generic provider rather than through Shape resolution.
     //
-    // A query cannot cross the wire live (core 2.10.0 contract flip), so the client ships
-    // `toJSON()` and `fromJSON()` rehydrates it here into a live, closed query.
-    // `LinkedStorage` then routes it by the QUERY's shape — which is, and always was, what
-    // decides the target dataset. The store instance never participated.
+    // A query cannot cross the wire live, so the client ships `toJSON()` and `fromJSON()`
+    // rehydrates it here into a live, closed query. `LinkedStorage` then routes it by the
+    // QUERY's shape, which is what decides the target dataset; the store instance never
+    // participates.
     //
     // Every query is checked first against the access rules of the stores it
     // maps to, declared in the app's storage config (`withAccess`; a store with
@@ -79,6 +82,12 @@ export default class LincdServerBackendProvider extends BackendProvider {
         return LinkedStorage.deleteQuery(query);
     }
 }
+__decorate([
+    callable('public'),
+    __metadata("design:type", Function),
+    __metadata("design:paramtypes", []),
+    __metadata("design:returntype", Promise)
+], LincdServerBackendProvider.prototype, "ping", null);
 __decorate([
     callable('public'),
     __metadata("design:type", Function),

package/lib/esm/backend.js.map

@@ -1 +1 @@
-{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/backend.ts"],"names":[],"mappings":"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","sourcesContent":["import { BackendProvider } from '@_linked/server-utils/utils/BackendProvider';\nimport { callable } from '@_linked/server-utils/utils/callable';\nimport { LinkedFileStorage } from '@_linked/core/utils/LinkedFileStorage';\nimport { LinkedStorage } from '@_linked/core/utils/LinkedStorage';\nimport { LocalFileStore } from './shapes/filestores/LocalFileStore.js';\nimport { authorizeGenericQuery, toQueryBuilder } from './utils/queryPlane.js';\nimport path from 'path';\nimport fs from 'fs/promises';\n\nexport default class LincdServerBackendProvider extends BackendProvider {\n  async setupBeforeControllers() {\n    if (!LinkedFileStorage.getDefaultStore()) {\n      LinkedFileStorage.setDefaultStore(\n        new LocalFileStore(process.env.NODE_ENV + '-filestore')\n      );\n    }\n    let fileSystemUploadPath = path.join('data', 'filestores');\n    try {\n      await fs.access(fileSystemUploadPath);\n    } catch (err) {\n      await fs.mkdir(path.join(fileSystemUploadPath, 'filestores'), {\n        recursive: true,\n      });\n    }\n  }\n\n  // ── BackendAPIStore query execution ──────────────────────────────────────\n  //\n  // These answer the frontend `BackendAPIStore`, which calls\n  // `Server.call(packageName, {method}, json)` — the PACKAGE form, so the request\n  // arrives here on the generic provider rather than through Shape resolution.\n  //\n  // They used to live on `BackendAPIStoreProvider`, a `ShapeProvider`, whose methods\n  // took the store as a first argument and never read it. Reaching that provider meant\n  // the transport had to carry a `shapeURI` and an `instanceNode`, and the server had to\n  // rebuild the store with `new (providerShapeClass)({id})` — instantiating a Shape only\n  // to discard it. Addressing by package removes all of that.\n  //\n  // A query cannot cross the wire live (core 2.10.0 contract flip), so the client ships\n  // `toJSON()` and `fromJSON()` rehydrates it here into a live, closed query.\n  // `LinkedStorage` then routes it by the QUERY's shape — which is, and always was, what\n  // decides the target dataset. The store instance never participated.\n\n  //\n  // Every query is checked first against the access rules of the stores it\n  // maps to, declared in the app's storage config (`withAccess`; a store with\n  // no rule requires a session): see utils/queryPlane. INTERIM model, to be\n  // rethought. The store runs the builder that was checked. They are declared\n  // 'public' because that check, not the RPC layer, decides whether a session\n  // is required.\n\n  @callable('public')\n  async selectQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('select', json, query, 'selectQuery');\n    return LinkedStorage.selectQuery(query);\n  }\n\n  @callable('public')\n  async askQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('ask', json, query, 'askQuery');\n    return LinkedStorage.askQuery(query);\n  }\n\n  @callable('public')\n  async updateQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('update', json, query, 'updateQuery');\n    return LinkedStorage.updateQuery(query);\n  }\n\n  @callable('public')\n  async createQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('create', json, query, 'createQuery');\n    return LinkedStorage.createQuery(query);\n  }\n\n  @callable('public')\n  async deleteQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('delete', json, query, 'deleteQuery');\n    return LinkedStorage.deleteQuery(query);\n  }\n}\n"]}
+{"version":3,"file":"backend.js","sourceRoot":"","sources":["../../src/backend.ts"],"names":[],"mappings":"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","sourcesContent":["import { BackendProvider } from '@_linked/server-utils/utils/BackendProvider';\nimport { callable } from '@_linked/server-utils/utils/callable';\nimport { LinkedFileStorage } from '@_linked/core/utils/LinkedFileStorage';\nimport { LinkedStorage } from '@_linked/core/utils/LinkedStorage';\nimport { LocalFileStore } from './shapes/filestores/LocalFileStore.js';\nimport { authorizeGenericQuery, toQueryBuilder } from './utils/queryPlane.js';\nimport path from 'path';\nimport fs from 'fs/promises';\n\nexport default class LincdServerBackendProvider extends BackendProvider {\n  async setupBeforeControllers() {\n    if (!LinkedFileStorage.getDefaultStore()) {\n      LinkedFileStorage.setDefaultStore(\n        new LocalFileStore(process.env.NODE_ENV + '-filestore')\n      );\n    }\n    let fileSystemUploadPath = path.join('data', 'filestores');\n    try {\n      await fs.access(fileSystemUploadPath);\n    } catch (err) {\n      await fs.mkdir(path.join(fileSystemUploadPath, 'filestores'), {\n        recursive: true,\n      });\n    }\n  }\n\n  /**\n   * Reachability check for a `RemoteDataset` pointed at this server: reads nothing, changes\n   * nothing. A plain linked server has no token concept, so it always answers `{ok: true}`;\n   * a host that serves the wire with tokens answers 401 for a refused one.\n   */\n  @callable('public')\n  async ping(): Promise<{ ok: true }> {\n    return { ok: true };\n  }\n\n  // ── Generic query execution ──────────────────────────────────────────────\n  //\n  // These answer `RemoteDataset`: a browser's store calls\n  // `Server.call(packageName, {method}, json)` (the PACKAGE form), and a remote app's store\n  // posts the same `{args}` body to `{url}/call/@_linked/server/<method>`. Either way the\n  // request arrives here on the generic provider rather than through Shape resolution.\n  //\n  // A query cannot cross the wire live, so the client ships `toJSON()` and `fromJSON()`\n  // rehydrates it here into a live, closed query. `LinkedStorage` then routes it by the\n  // QUERY's shape, which is what decides the target dataset; the store instance never\n  // participates.\n  //\n  // Every query is checked first against the access rules of the stores it\n  // maps to, declared in the app's storage config (`withAccess`; a store with\n  // no rule requires a session): see utils/queryPlane. INTERIM model, to be\n  // rethought. The store runs the builder that was checked. They are declared\n  // 'public' because that check, not the RPC layer, decides whether a session\n  // is required.\n\n  @callable('public')\n  async selectQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('select', json, query, 'selectQuery');\n    return LinkedStorage.selectQuery(query);\n  }\n\n  @callable('public')\n  async askQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('ask', json, query, 'askQuery');\n    return LinkedStorage.askQuery(query);\n  }\n\n  @callable('public')\n  async updateQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('update', json, query, 'updateQuery');\n    return LinkedStorage.updateQuery(query);\n  }\n\n  @callable('public')\n  async createQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('create', json, query, 'createQuery');\n    return LinkedStorage.createQuery(query);\n  }\n\n  @callable('public')\n  async deleteQuery(json: any) {\n    const query = toQueryBuilder(json);\n    await authorizeGenericQuery('delete', json, query, 'deleteQuery');\n    return LinkedStorage.deleteQuery(query);\n  }\n}\n"]}

package/lib/esm/index.d.ts

@@ -1,7 +1,7 @@
 import './types.js';
 import './ontologies/server.register.js';
 import './shapes/index.js';
-import './shapes/quadstores/BackendAPIStore.js';
+import './shapes/quadstores/RemoteDataset.js';
 import './shapes/filestores/LocalFileStore.js';
 import './utils/accessUrl.js';
 export { FatalStartupError, isFatalError } from './utils/fatalError.js';

package/lib/esm/index.js

@@ -3,7 +3,7 @@ import './ontologies/server.register.js';
 //SHAPES FIRST
 import './shapes/index.js';
 // Not shapes (plain store classes); kept so the entry's module graph is unchanged.
-import './shapes/quadstores/BackendAPIStore.js';
+import './shapes/quadstores/RemoteDataset.js';
 import './shapes/filestores/LocalFileStore.js';
 //THEN COMPONENTS
 import './utils/accessUrl.js';

package/lib/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,CAAC;AACpB,OAAO,iCAAiC,CAAC;AAEzC,cAAc;AACd,OAAO,mBAAmB,CAAC;AAC3B,mFAAmF;AACnF,OAAO,wCAAwC,CAAC;AAChD,OAAO,uCAAuC,CAAC;AAE/C,iBAAiB;AACjB,OAAO,sBAAsB,CAAC;AAE9B,8EAA8E;AAC9E,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC","sourcesContent":["import './types.js';\nimport './ontologies/server.register.js';\n\n//SHAPES FIRST\nimport './shapes/index.js';\n// Not shapes (plain store classes); kept so the entry's module graph is unchanged.\nimport './shapes/quadstores/BackendAPIStore.js';\nimport './shapes/filestores/LocalFileStore.js';\n\n//THEN COMPONENTS\nimport './utils/accessUrl.js';\n\n// The fatal-error contract a provider uses to refuse to let the server start.\nexport { FatalStartupError, isFatalError } from './utils/fatalError.js';\nexport type { FatalError } from './utils/fatalError.js';\n\n//TYPES — re-exported from @_linked/server-utils (canonical location)\nexport type {\n  RouteConfig,\n  RoutesConfig,\n  RoutesModule,\n} from '@_linked/server-utils/types/RouteConfig';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,YAAY,CAAC;AACpB,OAAO,iCAAiC,CAAC;AAEzC,cAAc;AACd,OAAO,mBAAmB,CAAC;AAC3B,mFAAmF;AACnF,OAAO,sCAAsC,CAAC;AAC9C,OAAO,uCAAuC,CAAC;AAE/C,iBAAiB;AACjB,OAAO,sBAAsB,CAAC;AAE9B,8EAA8E;AAC9E,OAAO,EAAE,iBAAiB,EAAE,YAAY,EAAE,MAAM,uBAAuB,CAAC","sourcesContent":["import './types.js';\nimport './ontologies/server.register.js';\n\n//SHAPES FIRST\nimport './shapes/index.js';\n// Not shapes (plain store classes); kept so the entry's module graph is unchanged.\nimport './shapes/quadstores/RemoteDataset.js';\nimport './shapes/filestores/LocalFileStore.js';\n\n//THEN COMPONENTS\nimport './utils/accessUrl.js';\n\n// The fatal-error contract a provider uses to refuse to let the server start.\nexport { FatalStartupError, isFatalError } from './utils/fatalError.js';\nexport type { FatalError } from './utils/fatalError.js';\n\n//TYPES — re-exported from @_linked/server-utils (canonical location)\nexport type {\n  RouteConfig,\n  RoutesConfig,\n  RoutesModule,\n} from '@_linked/server-utils/types/RouteConfig';\n"]}

package/lib/esm/shapes/quadstores/RemoteDataset.d.ts

@@ -0,0 +1,100 @@
+import type { IDataset } from '@_linked/core/interfaces/IDataset';
+import type { SelectQuery } from '@_linked/core/queries/SelectQuery';
+import type { CountQuery } from '@_linked/core/queries/CountQuery';
+import type { AskQuery } from '@_linked/core/queries/AskQuery';
+import type { UpdateQuery } from '@_linked/core/queries/UpdateQuery';
+import type { CreateQuery } from '@_linked/core/queries/CreateQuery';
+import type { DeleteQuery, DeleteResponse } from '@_linked/core/queries/DeleteQuery';
+import type { SelectResult, UpdateResult, CreateResult } from '@_linked/core/queries/IntermediateRepresentation';
+/**
+ * Constructor argument for `new RemoteDataset(config)`: the `config` object of a
+ * `linked.{frontend,backend}.datasets.json` entry, passed verbatim.
+ */
+export interface RemoteDatasetConfig {
+    /**
+     * Base URL of the data server, e.g. `http://localhost:4040/gateway`; routes are appended
+     * to it. Without it, queries go to this process's own backend through `Server.call`.
+     * Present but empty is an error, never the no-url form.
+     */
+    url?: string;
+    /** Sent as `Authorization: Bearer <token>` when set and `url` is set. */
+    token?: string;
+    /** Stable name; becomes the suffix of the store URI: ${DATA_ROOT}/backend-api-store/<name>. */
+    name?: string;
+    /** Or pass a fully-qualified URI directly. */
+    id?: string;
+}
+/**
+ * A failed call to the data server at `url`. `status` is the HTTP status (0 when no HTTP
+ * answer came back); `code` is the error body's `code` when the server sent one.
+ */
+export declare class RemoteDatasetError extends Error {
+    /** The data server base url ('' when the configured url is empty). */
+    readonly url: string;
+    /** The HTTP status; 0 = no HTTP answer. */
+    readonly status: number;
+    /** The error body's `code`, when the server sent one. */
+    readonly code?: string;
+    constructor(message: string, url: string, status: number, code?: string);
+}
+/**
+ * Nothing at `url` speaks the query wire: no HTTP answer, an empty url, or (on `ping`) an
+ * answer that is not the server's. A boot that gets this should stop.
+ */
+export declare class RemoteDatasetUnreachableError extends RemoteDatasetError {
+}
+/** The data server answered 401 or 403: it refused this dataset's token. */
+export declare class RemoteDatasetUnauthorizedError extends RemoteDatasetError {
+}
+/**
+ * An {@link IDataset} whose queries are answered by a linked server.
+ *
+ * - **Without `url`** the server is this app's own backend: every query goes through
+ *   `Server.call`'s package form (`/call/@_linked/server/<method>` with a body of `{args}`),
+ *   and on a backend `Server`'s local shortcut answers it in process. This is the store a
+ *   browser uses to talk to its backend.
+ * - **With `url`** the server is a remote data server: every query posts
+ *   `{"args": [query.toJSON()]}` to `{url}/call/@_linked/server/<method>` with the bearer
+ *   `token`, through `fetch`, never through `Server` (whose local shortcut would answer the
+ *   app's own provider) and never retried (a retried write could apply twice). `init()` asks
+ *   the server's `ping` and throws {@link RemoteDatasetUnreachableError} or
+ *   {@link RemoteDatasetUnauthorizedError} when it cannot be used.
+ *
+ * A store is not a Shape: it addresses the backend by package name, so nothing about the
+ * store instance crosses the wire. Query routing is decided by the query's shape.
+ *
+ * `LinkedStorage.setDefaultDataset` calls `init()` without awaiting it, so a boot that must
+ * fail loudly awaits `init()` itself first; a successful `init()` is memoized.
+ */
+export declare class RemoteDataset implements IDataset {
+    /**
+     * Kept so the config form is still accepted and a store can be named; it is not an
+     * addressing mechanism, nothing transmits or resolves it.
+     */
+    readonly id?: string;
+    /** The data server base url, trailing slashes trimmed; undefined in the no-url form. */
+    readonly url?: string;
+    private readonly token?;
+    private initialized?;
+    constructor(config?: RemoteDatasetConfig | string);
+    init(): Promise<void>;
+    selectQuery(query: SelectQuery | CountQuery): Promise<SelectResult | number>;
+    askQuery(query: AskQuery): Promise<boolean>;
+    updateQuery(query: UpdateQuery): Promise<UpdateResult>;
+    createQuery(query: CreateQuery): Promise<CreateResult>;
+    deleteQuery(query: DeleteQuery): Promise<DeleteResponse>;
+    private call;
+    /**
+     * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no
+     * provider on the backend) rejects with a `ServerCallError` carrying the
+     * status and the server's message instead of reading as an empty result.
+     * Whatever a successful call returns, `undefined` included, resolves as is.
+     */
+    private callBackend;
+    /**
+     * The url form: one POST to `{url}/call/@_linked/server/<method>`. Resolves the parsed
+     * body (`null` is a valid result: a method that returned `undefined`). Messages name the
+     * url and the method, never the token.
+     */
+    private post;
+}

package/lib/esm/shapes/quadstores/RemoteDataset.js

@@ -0,0 +1,188 @@
+import { packageName } from '../../package.js';
+import { Server } from '@_linked/server-utils/utils/Server';
+/**
+ * A failed call to the data server at `url`. `status` is the HTTP status (0 when no HTTP
+ * answer came back); `code` is the error body's `code` when the server sent one.
+ */
+export class RemoteDatasetError extends Error {
+    constructor(message, url, status, code) {
+        super(message);
+        this.name = new.target.name;
+        this.url = url;
+        this.status = status;
+        if (code !== undefined)
+            this.code = code;
+    }
+}
+/**
+ * Nothing at `url` speaks the query wire: no HTTP answer, an empty url, or (on `ping`) an
+ * answer that is not the server's. A boot that gets this should stop.
+ */
+export class RemoteDatasetUnreachableError extends RemoteDatasetError {
+}
+/** The data server answered 401 or 403: it refused this dataset's token. */
+export class RemoteDatasetUnauthorizedError extends RemoteDatasetError {
+}
+/** On `ping`, these statuses mean nothing at that url serves the query wire. */
+const PING_UNREACHABLE_STATUSES = new Set([404, 501, 502, 503, 504]);
+/**
+ * An {@link IDataset} whose queries are answered by a linked server.
+ *
+ * - **Without `url`** the server is this app's own backend: every query goes through
+ *   `Server.call`'s package form (`/call/@_linked/server/<method>` with a body of `{args}`),
+ *   and on a backend `Server`'s local shortcut answers it in process. This is the store a
+ *   browser uses to talk to its backend.
+ * - **With `url`** the server is a remote data server: every query posts
+ *   `{"args": [query.toJSON()]}` to `{url}/call/@_linked/server/<method>` with the bearer
+ *   `token`, through `fetch`, never through `Server` (whose local shortcut would answer the
+ *   app's own provider) and never retried (a retried write could apply twice). `init()` asks
+ *   the server's `ping` and throws {@link RemoteDatasetUnreachableError} or
+ *   {@link RemoteDatasetUnauthorizedError} when it cannot be used.
+ *
+ * A store is not a Shape: it addresses the backend by package name, so nothing about the
+ * store instance crosses the wire. Query routing is decided by the query's shape.
+ *
+ * `LinkedStorage.setDefaultDataset` calls `init()` without awaiting it, so a boot that must
+ * fail loudly awaits `init()` itself first; a successful `init()` is memoized.
+ */
+export class RemoteDataset {
+    constructor(config) {
+        if (!config)
+            return;
+        if (typeof config === 'string') {
+            this.id = `${process.env.DATA_ROOT}/backend-api-store/${config}`;
+            return;
+        }
+        if (typeof config.url === 'string') {
+            this.url = config.url.trim().replace(/\/+$/, '');
+            const token = typeof config.token === 'string' ? config.token.trim() : '';
+            if (token)
+                this.token = token;
+        }
+        if (config.id) {
+            this.id = config.id;
+            return;
+        }
+        if (config.name) {
+            this.id = `${process.env.DATA_ROOT}/backend-api-store/${config.name}`;
+        }
+    }
+    init() {
+        // No initialization needed when queries are routed to the app's own backend.
+        if (this.url === undefined)
+            return Promise.resolve();
+        if (!this.initialized) {
+            this.initialized = this.post('ping', []).then(() => undefined, (err) => {
+                // Not memoized: the next init() asks again.
+                this.initialized = undefined;
+                throw err;
+            });
+        }
+        return this.initialized;
+    }
+    // Queries serialize to DSL-JSON for the wire: the live (closed) query can't cross a call
+    // as-is, so we ship `toJSON()` and the server's generic provider rehydrates it with
+    // `fromJSON()`.
+    selectQuery(query) {
+        return this.call('selectQuery', query.toJSON());
+    }
+    askQuery(query) {
+        return this.call('askQuery', query.toJSON());
+    }
+    updateQuery(query) {
+        return this.call('updateQuery', query.toJSON());
+    }
+    createQuery(query) {
+        return this.call('createQuery', query.toJSON());
+    }
+    deleteQuery(query) {
+        return this.call('deleteQuery', query.toJSON());
+    }
+    call(method, json) {
+        if (this.url === undefined)
+            return this.callBackend(method, json);
+        return this.post(method, [json]);
+    }
+    /**
+     * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no
+     * provider on the backend) rejects with a `ServerCallError` carrying the
+     * status and the server's message instead of reading as an empty result.
+     * Whatever a successful call returns, `undefined` included, resolves as is.
+     */
+    callBackend(method, json) {
+        // The PACKAGE form, not the shape form. It posts to
+        // `/call/<packageName>/<method>` with a body of `{args}` only — no `shapeURI`,
+        // no `instanceNode` — and the backend answers from this package's generic
+        // provider without resolving or instantiating any Shape.
+        return Server.call(packageName, { method, rejectOnError: true }, json);
+    }
+    /**
+     * The url form: one POST to `{url}/call/@_linked/server/<method>`. Resolves the parsed
+     * body (`null` is a valid result: a method that returned `undefined`). Messages name the
+     * url and the method, never the token.
+     */
+    async post(method, args) {
+        var _a;
+        const base = (_a = this.url) !== null && _a !== void 0 ? _a : '';
+        if (!base) {
+            throw new RemoteDatasetUnreachableError(`RemoteDataset: no data server url is set (the configured url is empty); cannot ${method}`, '', 0);
+        }
+        const target = `${base}/call/${packageName}/${method}`;
+        const headers = {
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+        if (this.token)
+            headers.Authorization = `Bearer ${this.token}`;
+        let response;
+        try {
+            response = await globalThis.fetch(target, {
+                method: 'POST',
+                headers,
+                body: JSON.stringify({ args }),
+            });
+        }
+        catch (err) {
+            const cause = err instanceof Error ? err.message : String(err);
+            throw new RemoteDatasetUnreachableError(`RemoteDataset: cannot reach the data server at ${base} (${method}): ${cause}`, base, 0);
+        }
+        const text = await response.text();
+        let body = undefined;
+        let isJson = false;
+        if (text) {
+            try {
+                body = JSON.parse(text);
+                isJson = true;
+            }
+            catch (_b) {
+                body = text;
+            }
+        }
+        if (response.ok) {
+            if (isJson)
+                return body;
+            if (method === 'ping') {
+                throw new RemoteDatasetUnreachableError(`RemoteDataset: the data server at ${base} answered ping with a body that is not JSON`, base, response.status);
+            }
+            if (!text)
+                return undefined;
+            throw new RemoteDatasetError(`RemoteDataset: the data server at ${base} answered ${method} with a body that is not JSON`, base, response.status);
+        }
+        const record = body && typeof body === 'object' ? body : undefined;
+        const code = typeof (record === null || record === void 0 ? void 0 : record.code) === 'string' ? record.code : undefined;
+        const detail = typeof (record === null || record === void 0 ? void 0 : record.error) === 'string'
+            ? record.error
+            : typeof body === 'string' && body
+                ? body
+                : response.statusText;
+        const message = `RemoteDataset: the data server at ${base} answered ${method} with ${response.status}${code ? ` (${code})` : ''}${detail ? `: ${detail}` : ''}`;
+        if (response.status === 401 || response.status === 403) {
+            throw new RemoteDatasetUnauthorizedError(message, base, response.status, code);
+        }
+        if (method === 'ping' && (PING_UNREACHABLE_STATUSES.has(response.status) || !isJson)) {
+            throw new RemoteDatasetUnreachableError(message, base, response.status, code);
+        }
+        throw new RemoteDatasetError(message, base, response.status, code);
+    }
+}
+//# sourceMappingURL=RemoteDataset.js.map

package/lib/esm/shapes/quadstores/RemoteDataset.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"RemoteDataset.js","sourceRoot":"","sources":["../../../../src/shapes/quadstores/RemoteDataset.ts"],"names":[],"mappings":"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","sourcesContent":["import { packageName } from '../../package.js';\nimport { Server } from '@_linked/server-utils/utils/Server';\nimport type { IDataset } from '@_linked/core/interfaces/IDataset';\nimport type { SelectQuery } from '@_linked/core/queries/SelectQuery';\nimport type { CountQuery } from '@_linked/core/queries/CountQuery';\nimport type { AskQuery } from '@_linked/core/queries/AskQuery';\nimport type { UpdateQuery } from '@_linked/core/queries/UpdateQuery';\nimport type { CreateQuery } from '@_linked/core/queries/CreateQuery';\nimport type {\n  DeleteQuery,\n  DeleteResponse,\n} from '@_linked/core/queries/DeleteQuery';\nimport type {\n  SelectResult,\n  UpdateResult,\n  CreateResult,\n} from '@_linked/core/queries/IntermediateRepresentation';\n\n/**\n * Constructor argument for `new RemoteDataset(config)`: the `config` object of a\n * `linked.{frontend,backend}.datasets.json` entry, passed verbatim.\n */\nexport interface RemoteDatasetConfig {\n  /**\n   * Base URL of the data server, e.g. `http://localhost:4040/gateway`; routes are appended\n   * to it. Without it, queries go to this process's own backend through `Server.call`.\n   * Present but empty is an error, never the no-url form.\n   */\n  url?: string;\n  /** Sent as `Authorization: Bearer <token>` when set and `url` is set. */\n  token?: string;\n  /** Stable name; becomes the suffix of the store URI: ${DATA_ROOT}/backend-api-store/<name>. */\n  name?: string;\n  /** Or pass a fully-qualified URI directly. */\n  id?: string;\n}\n\n/**\n * A failed call to the data server at `url`. `status` is the HTTP status (0 when no HTTP\n * answer came back); `code` is the error body's `code` when the server sent one.\n */\nexport class RemoteDatasetError extends Error {\n  /** The data server base url ('' when the configured url is empty). */\n  readonly url: string;\n  /** The HTTP status; 0 = no HTTP answer. */\n  readonly status: number;\n  /** The error body's `code`, when the server sent one. */\n  readonly code?: string;\n\n  constructor(message: string, url: string, status: number, code?: string) {\n    super(message);\n    this.name = new.target.name;\n    this.url = url;\n    this.status = status;\n    if (code !== undefined) this.code = code;\n  }\n}\n\n/**\n * Nothing at `url` speaks the query wire: no HTTP answer, an empty url, or (on `ping`) an\n * answer that is not the server's. A boot that gets this should stop.\n */\nexport class RemoteDatasetUnreachableError extends RemoteDatasetError {}\n\n/** The data server answered 401 or 403: it refused this dataset's token. */\nexport class RemoteDatasetUnauthorizedError extends RemoteDatasetError {}\n\ntype Method =\n  | 'ping'\n  | 'selectQuery'\n  | 'askQuery'\n  | 'updateQuery'\n  | 'createQuery'\n  | 'deleteQuery';\n\n/** On `ping`, these statuses mean nothing at that url serves the query wire. */\nconst PING_UNREACHABLE_STATUSES = new Set([404, 501, 502, 503, 504]);\n\n/**\n * An {@link IDataset} whose queries are answered by a linked server.\n *\n * - **Without `url`** the server is this app's own backend: every query goes through\n *   `Server.call`'s package form (`/call/@_linked/server/<method>` with a body of `{args}`),\n *   and on a backend `Server`'s local shortcut answers it in process. This is the store a\n *   browser uses to talk to its backend.\n * - **With `url`** the server is a remote data server: every query posts\n *   `{\"args\": [query.toJSON()]}` to `{url}/call/@_linked/server/<method>` with the bearer\n *   `token`, through `fetch`, never through `Server` (whose local shortcut would answer the\n *   app's own provider) and never retried (a retried write could apply twice). `init()` asks\n *   the server's `ping` and throws {@link RemoteDatasetUnreachableError} or\n *   {@link RemoteDatasetUnauthorizedError} when it cannot be used.\n *\n * A store is not a Shape: it addresses the backend by package name, so nothing about the\n * store instance crosses the wire. Query routing is decided by the query's shape.\n *\n * `LinkedStorage.setDefaultDataset` calls `init()` without awaiting it, so a boot that must\n * fail loudly awaits `init()` itself first; a successful `init()` is memoized.\n */\nexport class RemoteDataset implements IDataset {\n  /**\n   * Kept so the config form is still accepted and a store can be named; it is not an\n   * addressing mechanism, nothing transmits or resolves it.\n   */\n  readonly id?: string;\n  /** The data server base url, trailing slashes trimmed; undefined in the no-url form. */\n  readonly url?: string;\n  private readonly token?: string;\n  private initialized?: Promise<void>;\n\n  constructor(config?: RemoteDatasetConfig | string) {\n    if (!config) return;\n    if (typeof config === 'string') {\n      this.id = `${process.env.DATA_ROOT}/backend-api-store/${config}`;\n      return;\n    }\n    if (typeof config.url === 'string') {\n      this.url = config.url.trim().replace(/\\/+$/, '');\n      const token = typeof config.token === 'string' ? config.token.trim() : '';\n      if (token) this.token = token;\n    }\n    if (config.id) {\n      this.id = config.id;\n      return;\n    }\n    if (config.name) {\n      this.id = `${process.env.DATA_ROOT}/backend-api-store/${config.name}`;\n    }\n  }\n\n  init(): Promise<void> {\n    // No initialization needed when queries are routed to the app's own backend.\n    if (this.url === undefined) return Promise.resolve();\n    if (!this.initialized) {\n      this.initialized = this.post('ping', []).then(\n        () => undefined,\n        (err) => {\n          // Not memoized: the next init() asks again.\n          this.initialized = undefined;\n          throw err;\n        },\n      );\n    }\n    return this.initialized;\n  }\n\n  // Queries serialize to DSL-JSON for the wire: the live (closed) query can't cross a call\n  // as-is, so we ship `toJSON()` and the server's generic provider rehydrates it with\n  // `fromJSON()`.\n  selectQuery(query: SelectQuery | CountQuery): Promise<SelectResult | number> {\n    return this.call('selectQuery', query.toJSON());\n  }\n\n  askQuery(query: AskQuery): Promise<boolean> {\n    return this.call('askQuery', query.toJSON());\n  }\n\n  updateQuery(query: UpdateQuery): Promise<UpdateResult> {\n    return this.call('updateQuery', query.toJSON());\n  }\n\n  createQuery(query: CreateQuery): Promise<CreateResult> {\n    return this.call('createQuery', query.toJSON());\n  }\n\n  deleteQuery(query: DeleteQuery): Promise<DeleteResponse> {\n    return this.call('deleteQuery', query.toJSON());\n  }\n\n  private call<T>(method: Method, json: unknown): Promise<T> {\n    if (this.url === undefined) return this.callBackend(method, json);\n    return this.post(method, [json]) as Promise<T>;\n  }\n\n  /**\n   * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no\n   * provider on the backend) rejects with a `ServerCallError` carrying the\n   * status and the server's message instead of reading as an empty result.\n   * Whatever a successful call returns, `undefined` included, resolves as is.\n   */\n  private callBackend<T>(method: string, json: unknown): Promise<T> {\n    // The PACKAGE form, not the shape form. It posts to\n    // `/call/<packageName>/<method>` with a body of `{args}` only — no `shapeURI`,\n    // no `instanceNode` — and the backend answers from this package's generic\n    // provider without resolving or instantiating any Shape.\n    return Server.call(packageName, { method, rejectOnError: true }, json);\n  }\n\n  /**\n   * The url form: one POST to `{url}/call/@_linked/server/<method>`. Resolves the parsed\n   * body (`null` is a valid result: a method that returned `undefined`). Messages name the\n   * url and the method, never the token.\n   */\n  private async post(method: Method, args: unknown[]): Promise<unknown> {\n    const base = this.url ?? '';\n    if (!base) {\n      throw new RemoteDatasetUnreachableError(\n        `RemoteDataset: no data server url is set (the configured url is empty); cannot ${method}`,\n        '',\n        0,\n      );\n    }\n    const target = `${base}/call/${packageName}/${method}`;\n    const headers: Record<string, string> = {\n      'Content-Type': 'application/json',\n      Accept: 'application/json',\n    };\n    if (this.token) headers.Authorization = `Bearer ${this.token}`;\n\n    let response: Response;\n    try {\n      response = await globalThis.fetch(target, {\n        method: 'POST',\n        headers,\n        body: JSON.stringify({ args }),\n      });\n    } catch (err) {\n      const cause = err instanceof Error ? err.message : String(err);\n      throw new RemoteDatasetUnreachableError(\n        `RemoteDataset: cannot reach the data server at ${base} (${method}): ${cause}`,\n        base,\n        0,\n      );\n    }\n\n    const text = await response.text();\n    let body: unknown = undefined;\n    let isJson = false;\n    if (text) {\n      try {\n        body = JSON.parse(text);\n        isJson = true;\n      } catch {\n        body = text;\n      }\n    }\n\n    if (response.ok) {\n      if (isJson) return body;\n      if (method === 'ping') {\n        throw new RemoteDatasetUnreachableError(\n          `RemoteDataset: the data server at ${base} answered ping with a body that is not JSON`,\n          base,\n          response.status,\n        );\n      }\n      if (!text) return undefined;\n      throw new RemoteDatasetError(\n        `RemoteDataset: the data server at ${base} answered ${method} with a body that is not JSON`,\n        base,\n        response.status,\n      );\n    }\n\n    const record = body && typeof body === 'object' ? (body as Record<string, unknown>) : undefined;\n    const code = typeof record?.code === 'string' ? record.code : undefined;\n    const detail =\n      typeof record?.error === 'string'\n        ? record.error\n        : typeof body === 'string' && body\n          ? body\n          : response.statusText;\n    const message = `RemoteDataset: the data server at ${base} answered ${method} with ${response.status}${\n      code ? ` (${code})` : ''\n    }${detail ? `: ${detail}` : ''}`;\n\n    if (response.status === 401 || response.status === 403) {\n      throw new RemoteDatasetUnauthorizedError(message, base, response.status, code);\n    }\n    if (method === 'ping' && (PING_UNREACHABLE_STATUSES.has(response.status) || !isJson)) {\n      throw new RemoteDatasetUnreachableError(message, base, response.status, code);\n    }\n    throw new RemoteDatasetError(message, base, response.status, code);\n  }\n}\n"]}

package/package.json

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

package/readme.md

@@ -19,6 +19,10 @@ If you want to further adjust the functionality of LincdServer yourself, either
   - [Generic backend providers](#generic-backend-providers)
   - [Gotchas](#gotchas)
   - [Error semantics](#error-semantics)
+- [Query stores](#query-stores)
+  - [Without `url`](#without-url)
+  - [With `url`](#with-url)
+  - [`ping`](#ping)
 - [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)
@@ -230,7 +234,86 @@ What the caller sees depends on how it calls:
 - **`Server.call` on the backend.** Here it calls the `LinkedServer` directly.
   - A provider method that throws always rejects.
   - An unmatched call resolves `undefined` by default and rejects with a 501 `ServerCallError` when `rejectOnError` is set.
-- **`BackendAPIStore`.** It always uses `rejectOnError`, so a failed query rejects with the status and message. A successful call resolves with whatever the provider returned, `undefined` included.
+- **`RemoteDataset` without `url`.** It always uses `rejectOnError`, so a failed query rejects with the status and message. A successful call resolves with whatever the provider returned, `undefined` included.
+
+## Query stores
+
+`RemoteDataset` is an `IDataset` whose Linked Queries are answered by a linked server instead of
+by the store itself. It ships `query.toJSON()` and resolves with the plain JSON the server
+returns; it offers no raw SPARQL (`rawQuery`), dataset administration or change feed.
+
+Export path `@_linked/server/shapes/quadstores/RemoteDataset` (named export `RemoteDataset`, so
+`loadStores` resolves it by the last path segment). One class, two forms:
+
+| | no `url` | with `url` |
+| --- | --- | --- |
+| Answered by | this app's own backend | a remote data server, e.g. a host's gateway |
+| Sends through | `Server.call`'s package form (`/call/@_linked/server/<method>`); on a backend, `Server`'s local shortcut | `globalThis.fetch` to `{url}/call/@_linked/server/<method>`, never `Server` |
+| Authenticated by | the user's session | `Authorization: Bearer <token>` |
+| `init()` | resolves at once | posts `ping`, throws a typed error when the server cannot be used |
+| Typical config | `linked.frontend.datasets.json` | `linked.backend.datasets.json` |
+
+```typescript
+export interface RemoteDatasetConfig {
+  url?: string;   // data server base, e.g. http://localhost:4040/gateway; routes are appended
+  token?: string; // sent as Authorization: Bearer <token> when set and url is set
+  name?: string;  // id = ${DATA_ROOT}/backend-api-store/<name>; does not affect routing
+  id?: string;
+}
+```
+
+`new RemoteDataset('main')` is the `name` form.
+
+### Without `url`
+
+Every query is `Server.call(packageName, { method, rejectOnError: true }, query.toJSON())`, and
+this package's generic provider answers it from the backend's `LinkedStorage`. Its error
+semantics are under [Error semantics](#error-semantics). `token` is ignored.
+
+### With `url`
+
+```json
+{
+  "datasets": {
+    "appData": {
+      "store": "@_linked/server/shapes/quadstores/RemoteDataset",
+      "config": { "url": "${DATA_SERVER_URL:-}", "token": "${DATA_SERVER_TOKEN:-}" }
+    }
+  }
+}
+```
+
+- Each method posts `{"args": [<query.toJSON()>]}` to `{url}/call/@_linked/server/<method>`
+  (`selectQuery`, which also carries counts, `askQuery`, `updateQuery`, `createQuery`,
+  `deleteQuery`) with `Content-Type` and `Accept` set to `application/json` and, when `token` is
+  non-empty, `Authorization: Bearer <token>`. It resolves the parsed body; `null` is a valid
+  result. No other headers are sent and nothing is retried, so a write is never applied twice.
+- Trailing slashes are trimmed from `url`. A `url` that is present but empty (an unset
+  `${DATA_SERVER_URL:-}`) never falls back to the no-url form: `init()` and every method throw
+  `RemoteDatasetUnreachableError` with `url: ''`.
+- `init()` posts `{"args": []}` to `{url}/call/@_linked/server/ping`. A success is memoized; after
+  a failure the next `init()` asks again. `LinkedStorage.setDefaultDataset` does not await
+  `init()`, so a boot that must fail loudly awaits it itself before registering the store.
+- Errors, each carrying `url` (the base), `status` (0 when no HTTP answer came back) and `code`
+  (the error body's `code`, when the server sent one). Messages name the url and the method,
+  never the token.
+
+  | Answer | Error |
+  | --- | --- |
+  | no HTTP answer | `RemoteDatasetUnreachableError` (status 0) |
+  | 401 or 403 | `RemoteDatasetUnauthorizedError` |
+  | on `ping` only: 404, 501, 502, 503, 504, or a body that is not JSON | `RemoteDatasetUnreachableError` |
+  | any other non-2xx | `RemoteDatasetError` |
+
+  `RemoteDatasetUnreachableError` and `RemoteDatasetUnauthorizedError` extend
+  `RemoteDatasetError`, which extends `Error`; match them with `instanceof`.
+
+### `ping`
+
+`POST /call/@_linked/server/ping` (a `public` method of this package's generic provider) reads
+nothing, changes nothing and answers `{ "ok": true }`. A plain linked server has no token
+concept; a host that serves the wire with tokens checks the token itself and answers 401 for a
+refused one.
 
 ## API-only servers (`server.apiOnly`)
 

package/lib/esm/shapes/quadstores/BackendAPIStore.d.ts

@@ -1,58 +0,0 @@
-import type { IDataset } from '@_linked/core/interfaces/IDataset';
-import type { SelectQuery } from '@_linked/core/queries/SelectQuery';
-import type { AskQuery } from '@_linked/core/queries/AskQuery';
-import type { UpdateQuery } from '@_linked/core/queries/UpdateQuery';
-import type { CreateQuery } from '@_linked/core/queries/CreateQuery';
-import type { DeleteQuery, DeleteResponse } from '@_linked/core/queries/DeleteQuery';
-import type { SelectResult, UpdateResult, CreateResult } from '@_linked/core/queries/IntermediateRepresentation';
-/**
- * Constructor argument for `new BackendAPIStore(config)`. Per the
- * docs/backlog/016-ejection-export-flow.md spec — a single JSON object
- * passed verbatim from linked.{frontend,backend}.datasets.json's `config`.
- */
-export interface BackendAPIStoreConfig {
-    /** Stable name; becomes the suffix of the store URI: ${DATA_ROOT}/backend-api-store/<name>. */
-    name?: string;
-    /** Or pass a fully-qualified URI directly. */
-    id?: string;
-}
-/**
- * Frontend-side store that routes all queries to the backend via `Server.call()`.
- * The backend's generic provider for this package executes them against the real store.
- *
- * A store is not a Shape. This class used to `extends Shape` and carry `@linkedShape`
- * with a `targetClass`, purely so that `Server.call(this, …)` could address it: the
- * transport derived the target from `shape instanceof Shape && shape.id` (the instance)
- * and `shapeClass.shape.id` (the class). Neither carried any meaning — the backend
- * provider never read the store it was handed, and query routing is decided by the
- * QUERY's shape, not the store's.
- *
- * It now uses `Server.call`'s package form instead, which addresses the backend by
- * package name and sends no shape fields at all. That removes the last reason for this
- * class to be a Shape, and with it the `new (providerShapeClass)({id})` the backend had
- * to perform to rebuild a store instance nobody used.
- */
-export declare class BackendAPIStore implements IDataset {
-    /**
-     * Kept so the config form is still accepted and a store can be named, but it is no
-     * longer an addressing mechanism — nothing transmits or resolves it. Retained because
-     * `linked.{frontend,backend}.datasets.json` may still pass `name`/`id`.
-     */
-    readonly id?: string;
-    constructor(config?: BackendAPIStoreConfig | string | {
-        id?: string;
-    });
-    init(): Promise<void>;
-    selectQuery(query: SelectQuery): Promise<SelectResult>;
-    askQuery(query: AskQuery): Promise<boolean>;
-    updateQuery(query: UpdateQuery): Promise<UpdateResult>;
-    createQuery(query: CreateQuery): Promise<CreateResult>;
-    deleteQuery(query: DeleteQuery): Promise<DeleteResponse>;
-    /**
-     * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no
-     * provider on the backend) rejects with a `ServerCallError` carrying the
-     * status and the server's message instead of reading as an empty result.
-     * Whatever a successful call returns, `undefined` included, resolves as is.
-     */
-    private callBackend;
-}

package/lib/esm/shapes/quadstores/BackendAPIStore.js

@@ -1,71 +0,0 @@
-import { packageName } from '../../package.js';
-import { Server } from '@_linked/server-utils/utils/Server';
-/**
- * Frontend-side store that routes all queries to the backend via `Server.call()`.
- * The backend's generic provider for this package executes them against the real store.
- *
- * A store is not a Shape. This class used to `extends Shape` and carry `@linkedShape`
- * with a `targetClass`, purely so that `Server.call(this, …)` could address it: the
- * transport derived the target from `shape instanceof Shape && shape.id` (the instance)
- * and `shapeClass.shape.id` (the class). Neither carried any meaning — the backend
- * provider never read the store it was handed, and query routing is decided by the
- * QUERY's shape, not the store's.
- *
- * It now uses `Server.call`'s package form instead, which addresses the backend by
- * package name and sends no shape fields at all. That removes the last reason for this
- * class to be a Shape, and with it the `new (providerShapeClass)({id})` the backend had
- * to perform to rebuild a store instance nobody used.
- */
-export class BackendAPIStore {
-    constructor(config) {
-        if (!config)
-            return;
-        if (typeof config === 'string') {
-            this.id = `${process.env.DATA_ROOT}/backend-api-store/${config}`;
-            return;
-        }
-        if (config.id) {
-            this.id = config.id;
-            return;
-        }
-        if (config.name) {
-            const name = config.name;
-            this.id = `${process.env.DATA_ROOT}/backend-api-store/${name}`;
-        }
-    }
-    async init() {
-        // No initialization needed — queries are routed to the backend
-    }
-    // Queries serialize to DSL-JSON for the wire (core 2.10.0 contract flip): the
-    // live (closed) query can't cross Server.call as-is, so we ship `toJSON()` and
-    // the BackendAPIStoreProvider rehydrates with `fromJSON()` on the backend.
-    selectQuery(query) {
-        return this.callBackend('selectQuery', query.toJSON());
-    }
-    askQuery(query) {
-        return this.callBackend('askQuery', query.toJSON());
-    }
-    updateQuery(query) {
-        return this.callBackend('updateQuery', query.toJSON());
-    }
-    createQuery(query) {
-        return this.callBackend('createQuery', query.toJSON());
-    }
-    deleteQuery(query) {
-        return this.callBackend('deleteQuery', query.toJSON());
-    }
-    /**
-     * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no
-     * provider on the backend) rejects with a `ServerCallError` carrying the
-     * status and the server's message instead of reading as an empty result.
-     * Whatever a successful call returns, `undefined` included, resolves as is.
-     */
-    callBackend(method, json) {
-        // The PACKAGE form, not the shape form. It posts to
-        // `/call/<packageName>/<method>` with a body of `{args}` only — no `shapeURI`,
-        // no `instanceNode` — and the backend answers from this package's generic
-        // provider without resolving or instantiating any Shape.
-        return Server.call(packageName, { method, rejectOnError: true }, json);
-    }
-}
-//# sourceMappingURL=BackendAPIStore.js.map

package/lib/esm/shapes/quadstores/BackendAPIStore.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"BackendAPIStore.js","sourceRoot":"","sources":["../../../../src/shapes/quadstores/BackendAPIStore.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAC/C,OAAO,EAAE,MAAM,EAAE,MAAM,oCAAoC,CAAC;AA4B5D;;;;;;;;;;;;;;;GAeG;AACH,MAAM,OAAO,eAAe;IAQ1B,YAAY,MAAyD;QACnE,IAAI,CAAC,MAAM;YAAE,OAAO;QACpB,IAAI,OAAO,MAAM,KAAK,QAAQ,EAAE,CAAC;YAC/B,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,sBAAsB,MAAM,EAAE,CAAC;YACjE,OAAO;QACT,CAAC;QACD,IAAK,MAAgC,CAAC,EAAE,EAAE,CAAC;YACzC,IAAI,CAAC,EAAE,GAAI,MAAgC,CAAC,EAAG,CAAC;YAChD,OAAO;QACT,CAAC;QACD,IAAK,MAAgC,CAAC,IAAI,EAAE,CAAC;YAC3C,MAAM,IAAI,GAAI,MAAgC,CAAC,IAAK,CAAC;YACrD,IAAI,CAAC,EAAE,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,SAAS,sBAAsB,IAAI,EAAE,CAAC;QACjE,CAAC;IACH,CAAC;IAED,KAAK,CAAC,IAAI;QACR,+DAA+D;IACjE,CAAC;IAED,8EAA8E;IAC9E,+EAA+E;IAC/E,2EAA2E;IAC3E,WAAW,CAAC,KAAkB;QAC5B,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,QAAQ,CAAC,KAAe;QACtB,OAAO,IAAI,CAAC,WAAW,CAAC,UAAU,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACtD,CAAC;IAED,WAAW,CAAC,KAAkB;QAC5B,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,WAAW,CAAC,KAAkB;QAC5B,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED,WAAW,CAAC,KAAkB;QAC5B,OAAO,IAAI,CAAC,WAAW,CAAC,aAAa,EAAE,KAAK,CAAC,MAAM,EAAE,CAAC,CAAC;IACzD,CAAC;IAED;;;;;OAKG;IACK,WAAW,CAAI,MAAc,EAAE,IAAa;QAClD,oDAAoD;QACpD,+EAA+E;QAC/E,0EAA0E;QAC1E,yDAAyD;QACzD,OAAO,MAAM,CAAC,IAAI,CAAC,WAAW,EAAE,EAAE,MAAM,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,IAAI,CAAC,CAAC;IACzE,CAAC;CACF","sourcesContent":["import { packageName } from '../../package.js';\nimport { Server } from '@_linked/server-utils/utils/Server';\nimport type { IDataset } from '@_linked/core/interfaces/IDataset';\nimport type { SelectQuery } from '@_linked/core/queries/SelectQuery';\nimport type { AskQuery } from '@_linked/core/queries/AskQuery';\nimport type { UpdateQuery } from '@_linked/core/queries/UpdateQuery';\nimport type { CreateQuery } from '@_linked/core/queries/CreateQuery';\nimport type {\n  DeleteQuery,\n  DeleteResponse,\n} from '@_linked/core/queries/DeleteQuery';\nimport type {\n  SelectResult,\n  UpdateResult,\n  CreateResult,\n} from '@_linked/core/queries/IntermediateRepresentation';\n\n/**\n * Constructor argument for `new BackendAPIStore(config)`. Per the\n * docs/backlog/016-ejection-export-flow.md spec — a single JSON object\n * passed verbatim from linked.{frontend,backend}.datasets.json's `config`.\n */\nexport interface BackendAPIStoreConfig {\n  /** Stable name; becomes the suffix of the store URI: ${DATA_ROOT}/backend-api-store/<name>. */\n  name?: string;\n  /** Or pass a fully-qualified URI directly. */\n  id?: string;\n}\n\n/**\n * Frontend-side store that routes all queries to the backend via `Server.call()`.\n * The backend's generic provider for this package executes them against the real store.\n *\n * A store is not a Shape. This class used to `extends Shape` and carry `@linkedShape`\n * with a `targetClass`, purely so that `Server.call(this, …)` could address it: the\n * transport derived the target from `shape instanceof Shape && shape.id` (the instance)\n * and `shapeClass.shape.id` (the class). Neither carried any meaning — the backend\n * provider never read the store it was handed, and query routing is decided by the\n * QUERY's shape, not the store's.\n *\n * It now uses `Server.call`'s package form instead, which addresses the backend by\n * package name and sends no shape fields at all. That removes the last reason for this\n * class to be a Shape, and with it the `new (providerShapeClass)({id})` the backend had\n * to perform to rebuild a store instance nobody used.\n */\nexport class BackendAPIStore implements IDataset {\n  /**\n   * Kept so the config form is still accepted and a store can be named, but it is no\n   * longer an addressing mechanism — nothing transmits or resolves it. Retained because\n   * `linked.{frontend,backend}.datasets.json` may still pass `name`/`id`.\n   */\n  readonly id?: string;\n\n  constructor(config?: BackendAPIStoreConfig | string | { id?: string }) {\n    if (!config) return;\n    if (typeof config === 'string') {\n      this.id = `${process.env.DATA_ROOT}/backend-api-store/${config}`;\n      return;\n    }\n    if ((config as BackendAPIStoreConfig).id) {\n      this.id = (config as BackendAPIStoreConfig).id!;\n      return;\n    }\n    if ((config as BackendAPIStoreConfig).name) {\n      const name = (config as BackendAPIStoreConfig).name!;\n      this.id = `${process.env.DATA_ROOT}/backend-api-store/${name}`;\n    }\n  }\n\n  async init(): Promise<void> {\n    // No initialization needed — queries are routed to the backend\n  }\n\n  // Queries serialize to DSL-JSON for the wire (core 2.10.0 contract flip): the\n  // live (closed) query can't cross Server.call as-is, so we ship `toJSON()` and\n  // the BackendAPIStoreProvider rehydrates with `fromJSON()` on the backend.\n  selectQuery(query: SelectQuery): Promise<SelectResult> {\n    return this.callBackend('selectQuery', query.toJSON());\n  }\n\n  askQuery(query: AskQuery): Promise<boolean> {\n    return this.callBackend('askQuery', query.toJSON());\n  }\n\n  updateQuery(query: UpdateQuery): Promise<UpdateResult> {\n    return this.callBackend('updateQuery', query.toJSON());\n  }\n\n  createQuery(query: CreateQuery): Promise<CreateResult> {\n    return this.callBackend('createQuery', query.toJSON());\n  }\n\n  deleteQuery(query: DeleteQuery): Promise<DeleteResponse> {\n    return this.callBackend('deleteQuery', query.toJSON());\n  }\n\n  /**\n   * Opts in to `rejectOnError`, so a failed call (HTTP error status, or no\n   * provider on the backend) rejects with a `ServerCallError` carrying the\n   * status and the server's message instead of reading as an empty result.\n   * Whatever a successful call returns, `undefined` included, resolves as is.\n   */\n  private callBackend<T>(method: string, json: unknown): Promise<T> {\n    // The PACKAGE form, not the shape form. It posts to\n    // `/call/<packageName>/<method>` with a body of `{args}` only — no `shapeURI`,\n    // no `instanceNode` — and the backend answers from this package's generic\n    // provider without resolving or instantiating any Shape.\n    return Server.call(packageName, { method, rejectOnError: true }, json);\n  }\n}\n"]}