@_linked/core 2.18.1 → 2.20.1

package/CHANGELOG.md

@@ -1,5 +1,68 @@
 # Changelog
 
+## 2.20.1
+
+### Patch Changes
+
+- [#235](https://github.com/linked-fw/core/pull/235) [`19624f7`](https://github.com/linked-fw/core/commit/19624f7bb7b1d83bd99d9797a7da41fe7e09432b) Thanks [@flyon](https://github.com/flyon)! - Point `repository.url` at the linked-fw organisation, so npm provenance verification matches the repository that builds the package.
+
+## 2.20.0
+
+### Minor Changes
+
+- [#230](https://github.com/linked-fw/core/pull/230) [`bf8df0c`](https://github.com/linked-fw/core/commit/bf8df0c043cdb588e4b9f8baf97f87b340f0078b) Thanks [@flyon](https://github.com/flyon)! - Purpose-named file stores, save options and `statFile`.
+
+  - `LinkedFileStorage` gains a purpose registry: `registerPurpose`, `setStore`,
+    `getStore`, `hasStore`, `listPurposes` and `accessURLFor`. `getStore(purpose)`
+    returns the store configured for that purpose; a purpose that is registered
+    but not configured falls back to the default store (noted once with
+    `console.debug`); an unregistered
+    purpose throws, listing the known purposes, so a typo cannot silently write to
+    the wrong store. The well-known purposes `uploads` and `appAssets` are exported
+    as `FileStorePurposes` and registered at module load. `uploads` is an ordinary
+    purpose: `setDefaultStore` configures no purpose of its own, so `uploads`
+    resolves to the default store as a fallback, `hasStore('uploads')` is true only
+    after an explicit `setStore('uploads', store)`, and that call has the same
+    effect whether it runs before or after `setDefaultStore`.
+  - `getDefaultDataset`/`setDefaultDataset` are renamed to
+    `getDefaultStore`/`setDefaultStore`. The old names remain as `@deprecated`
+    aliases that forward, so no caller has to change; they will be dropped in the
+    next major.
+  - `IFileStore.saveFile` now takes `SaveFileOptions` (`mimeType`, `cacheControl`,
+    `metadata`, `preventDuplicates`) as its third argument, still accepting a
+    `string` there as the old positional `mimeType`. `normalizeSaveFileOptions` is
+    exported for implementations; it reports `preventDuplicates` as `undefined`
+    when the caller did not specify one — there is no core-wide default, so each
+    store keeps applying its own (`S3FileStore` overwrites, `LocalFileStore` adds a
+    random suffix). `options.preventDuplicates` wins over the positional argument.
+    `LinkedFileStorage.saveFile` likewise forwards an unspecified
+    `preventDuplicates` as `undefined` rather than `false`, so a
+    `saveFile(path, bytes)` call keeps behaving exactly as before.
+  - `IFileStore` gains an optional `statFile(filePath): Promise<FileStat | null>`
+    for verify-after-upload. Existing implementations stay valid.
+
+## 2.19.1
+
+### Patch Changes
+
+- [#231](https://github.com/linked-fw/core/pull/231) [`58a5b7a`](https://github.com/linked-fw/core/commit/58a5b7af7332584e9f40c16d17e303f18d86962a) Thanks [@flyon](https://github.com/flyon)! - Declare npm as the package manager for this repo and mark `package-lock.json` as a generated file.
+
+## 2.19.0
+
+### Minor Changes
+
+- [#224](https://github.com/linked-cm/core/pull/224) [`ea9971c`](https://github.com/linked-cm/core/commit/ea9971c6201f610102ad7674868602e1aaeb4e1f) Thanks [@flyon](https://github.com/flyon)! - Adds a root-level count to the query DSL: `SelectBuilder.from(shape).where(…).count()` and
+  `Shape.count()` resolve to a real `number`, lowering to `SELECT (COUNT(DISTINCT ?s) AS ?count)
+WHERE { … }`. Like an ask, a count is its own builder and IR kind, so `limit`/`offset` are dropped at
+  the boundary and unrepresentable thereafter — the count of a window is the count of the whole match
+  set. `.toCount()` is public so a router can forward the `{op: 'count'}` envelope instead of executing
+  it.
+
+  `IDataset.countQuery` is **optional**, so nothing breaks: every store extending `SparqlDataset` gets
+  it with no edit. A store or router that does not extend `SparqlDataset` — including any
+  `setQueryDispatch({…})` object literal in a consuming package — needs a `countQuery` arm added by
+  hand before `.count()` works against it; until then it fails loudly, naming the method.
+
 ## 2.18.1
 
 ### Patch Changes

package/README.md

@@ -362,6 +362,86 @@ LinkedStorage.setDefaultDataset(stores.appData);
 
 Each store class must accept a single config-object argument (`new StoreClass(config)`). `@_linked/fuseki`'s `FusekiStore` and `@_linked/server`'s `BackendAPIStore` both follow this contract.
 
+## File storage
+
+`LinkedStorage` routes *quads*; `LinkedFileStorage` routes *files*. Files are addressed by **purpose** — a short string naming what the files are for (`uploads`, `appAssets`, …) — so an app can send release bundles to a CDN bucket and user uploads to another store without any caller knowing which.
+
+```ts
+import {LinkedFileStorage, FileStorePurposes} from '@_linked/core';
+import {S3FileStore} from '@_linked/s3';
+
+LinkedFileStorage.setDefaultStore(new S3FileStore({/* … */}));           // fallback for every purpose
+LinkedFileStorage.setStore(FileStorePurposes.appAssets, new S3FileStore({/* cdn */}));
+
+await LinkedFileStorage.getStore(FileStorePurposes.appAssets).saveFile('/app.js', bytes);
+LinkedFileStorage.accessURLFor(FileStorePurposes.appAssets); // → https://cdn.example.com
+```
+
+### Resolution rule
+
+`getStore(purpose)` resolves in one order, and there is no fourth case:
+
+1. **configured** — a store was passed to `setStore(purpose, store)` → that store;
+2. **registered but not configured** → the default store, with a one-time `console.debug` line saying the purpose has no dedicated store (the normal case for a single-store app; it throws instead if no default store is set);
+3. **not registered** → throws, listing the known purposes. A typo like `'appAsset'` must not silently write release bundles into the uploads store.
+
+`uploads` is an ordinary purpose with no special case: `setDefaultStore` configures *no* purpose, so `uploads` reaches the default store through the fallback in step 2, and `setStore('uploads', other)` wins whether it is called before or after `setDefaultStore`.
+
+| Method | Meaning |
+| --- | --- |
+| `registerPurpose(purpose, {description?})` | Declare a purpose without configuring a store. |
+| `setStore(purpose, store)` | Configure (and register) the store; calls `store.init()`. |
+| `getStore(purpose)` | Resolve per the rule above. A **live reference** — call it per operation if config can change. |
+| `hasStore(purpose)` | Whether a store was *explicitly configured*. Ignores the fallback, so it is `false` while `getStore` still works. Never use it as a guard before `getStore`. |
+| `listPurposes()` | `{purpose, description?, configured}` for every declared purpose. |
+| `accessURLFor(purpose)` | The `accessURL` of the resolved store. |
+| `getDefaultStore()` / `setDefaultStore(store)` | The fallback store. `getDefaultDataset`/`setDefaultDataset` are `@deprecated` aliases that forward, kept until the next major. |
+
+### Introducing a purpose from a package
+
+Export the constant and register it **in the same module**, so importing the constant *is* the registration and load order resolves itself:
+
+```ts
+// @_linked/captures/purposes.ts
+import {LinkedFileStorage} from '@_linked/core';
+
+export const CapturesPurpose = 'captures';
+LinkedFileStorage.registerPurpose(CapturesPurpose, {description: '3D capture artifacts.'});
+```
+
+A consumer that imports `CapturesPurpose` can call `getStore(CapturesPurpose)` immediately; an app that never splits it out simply gets the default store. Core ships only `FileStorePurposes.uploads` and `FileStorePurposes.appAssets` — a new purpose belongs in the package that owns the concept.
+
+### Saving files: `SaveFileOptions`
+
+```ts
+await store.saveFile('/app.js', bytes, {
+  mimeType: 'application/javascript',
+  cacheControl: 'public, max-age=31536000, immutable',
+  metadata: {release: '1.2.3'},
+  preventDuplicates: true, // rename instead of overwriting when the path is taken
+});
+
+// Backwards compatible: a string third argument is read as the positional mimeType.
+await store.saveFile('/photo.webp', bytes, 'image/webp', true);
+```
+
+`options.preventDuplicates` wins over the positional fourth argument. Implementations should start with `normalizeSaveFileOptions(options, preventDuplicates)`, which collapses both forms into one object.
+
+> **There is no core-wide `preventDuplicates` default.** When a caller does not specify one it stays `undefined` all the way to the store, and **each store applies its own**: `LocalFileStore` adds a random suffix, `S3FileStore` overwrites. Pass it explicitly whenever the behaviour matters — never assume a default.
+
+### Optional `statFile`
+
+```ts
+const stat = await store.statFile?.('/app.js'); // FileStat | null | undefined
+if (!stat) {
+  // Store cannot report metadata, or the file is absent — skip verification.
+} else if (stat.sha256) {
+  // Only a real content hash verifies. `etag` is not one on S3.
+}
+```
+
+`statFile` is optional by design: a store without it still publishes. A caller must treat a missing method (`undefined`) or a missing `sha256` as "cannot verify" and continue, rather than failing the upload or falling back to `etag`.
+
 ## Automatic data validation
 
 SHACL shapes are ideal for data validation. Linked generates SHACL shapes from your TypeScript Shape classes, which you can sync to your store for schema-level validation. When your store enforces those shapes at runtime, you get both schema validation and runtime enforcement for extra safety.
@@ -381,7 +461,7 @@ The query DSL is schema-parameterized: you define your own SHACL shapes, and Lin
 - `and(...)` / `or(...)` combinations
 - Set filtering with `some(...)` / `every(...)` (and implicit `some`)
 - Outer `where(...)` chaining
-- Counting with `.size()`
+- Counting: `.count()` for how many instances match, `.size()` for a property's value count
 - Custom result formats (object mapping)
 - Computed values — derive new fields with arithmetic, string, date, and comparison methods
 - Expression-based WHERE filters (`p.name.strlen().gt(5)`)
@@ -487,12 +567,33 @@ const outer = await Person.select((p) => p.knows).where((p) =>
 );
 ```
 
-#### Counting (size)
+#### Counting
+
+Two different questions, two different queries.
+
+`.count()` answers **how many instances match** — one number for the whole match set. It respects
+`where` and `minus`, and ignores `limit`/`offset`, so a paged table can ask for its total row count
+beside the page it is showing:
+
+```typescript
+/* Result: number */
+const total = await Person.count();
+const matching = await Person.select().where((p) => p.name.equals('Semmy')).count();
+
+// Lowers to: SELECT (COUNT(DISTINCT ?a0) AS ?count) WHERE { ?a0 a Person ; name ?n . FILTER(…) }
+```
+
+`.size()` answers **how many values a property has**, per row:
+
 ```typescript
 /* Result: Array<{id: string; knows: number}> */
-const count = await Person.select((p) => p.knows.size());
+const perPerson = await Person.select((p) => p.knows.size());
 ```
 
+A count resolves to a real number and **rejects on failure** — it never reports an unreachable store
+as `0`. `.toCount()` gives you the count query itself, for a router that forwards
+(`builder.toCount().toJSON()`) rather than executes.
+
 #### Custom result formats
 ```typescript
 /* Result: Array<{id: string; nameIsMoa: boolean; numFriends: number}> */

package/lib/esm/index.d.ts

@@ -20,6 +20,9 @@ export type { QueryBuilderJSON } from './queries/QueryBuilder.js';
 export { AskBuilder, isAskQuery } from './queries/AskBuilder.js';
 export type { AskSpec } from './queries/AskBuilder.js';
 export type { AskQuery, AskQueryJSON, RawAskInput } from './queries/AskQuery.js';
+export { CountBuilder, isCountQuery } from './queries/CountBuilder.js';
+export type { CountSpec } from './queries/CountBuilder.js';
+export type { CountQuery, CountQueryJSON, RawCountInput } from './queries/CountQuery.js';
 export { CreateBuilder } from './queries/CreateBuilder.js';
 export { UpdateBuilder } from './queries/UpdateBuilder.js';
 export { DeleteBuilder } from './queries/DeleteBuilder.js';

package/lib/esm/index.js

@@ -22,6 +22,7 @@ export { PropertyPath, walkPropertyPath } from './queries/PropertyPath.js';
 export { FieldSet } from './queries/FieldSet.js';
 // Phase 3b — Mutation builders
 export { AskBuilder, isAskQuery } from './queries/AskBuilder.js';
+export { CountBuilder, isCountQuery } from './queries/CountBuilder.js';
 export { CreateBuilder } from './queries/CreateBuilder.js';
 export { UpdateBuilder } from './queries/UpdateBuilder.js';
 export { DeleteBuilder } from './queries/DeleteBuilder.js';

package/lib/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAC,UAAU,EAAE,SAAS,EAAC,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAC,OAAO,EAAC,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAC,uBAAuB,EAAC,MAAM,qCAAqC,CAAC;AAC5E,sEAAsE;AACtE,OAAO,EAAC,KAAK,EAAC,MAAM,mBAAmB,CAAC;AACxC,kEAAkE;AAClE,OAAO,EAAC,QAAQ,EAAE,WAAW,EAAE,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAQnF,OAAO,EAAC,aAAa,EAAC,MAAM,0BAA0B,CAAC;AACvD,2CAA2C;AAC3C,OAAO,EAAC,aAAa,EAAE,YAAY,EAAC,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAC,KAAK,EAAC,MAAM,oBAAoB,CAAC;AAEzC,OAAO,EAAC,QAAQ,EAAC,MAAM,uBAAuB,CAAC;AAE/C,OAAO,EACL,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAC,YAAY,EAAE,gBAAgB,EAAC,MAAM,2BAA2B,CAAC;AAEzE,sBAAsB;AACtB,OAAO,EAAC,QAAQ,EAAC,MAAM,uBAAuB,CAAC;AAM/C,+BAA+B;AAC/B,OAAO,EAAC,UAAU,EAAE,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAG/D,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AAGzD,8CAA8C;AAC9C,OAAO,EAAC,cAAc,EAAC,MAAM,iCAAiC,CAAC;AAE/D,OAAO,EAAC,IAAI,EAAC,MAAM,uBAAuB,CAAC;AAe3C,sEAAsE;AACtE,OAAO,EACL,cAAc,EACd,WAAW,GACZ,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,iBAAiB,GAClB,MAAM,gCAAgC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,OAAO,EAAC,UAAU,EAAE,SAAS,EAAC,MAAM,wBAAwB,CAAC;AAC7D,OAAO,EAAC,OAAO,EAAC,MAAM,kBAAkB,CAAC;AACzC,OAAO,EAAC,uBAAuB,EAAC,MAAM,qCAAqC,CAAC;AAC5E,sEAAsE;AACtE,OAAO,EAAC,KAAK,EAAC,MAAM,mBAAmB,CAAC;AACxC,kEAAkE;AAClE,OAAO,EAAC,QAAQ,EAAE,WAAW,EAAE,oBAAoB,EAAC,MAAM,wBAAwB,CAAC;AAQnF,OAAO,EAAC,aAAa,EAAC,MAAM,0BAA0B,CAAC;AACvD,2CAA2C;AAC3C,OAAO,EAAC,aAAa,EAAE,YAAY,EAAC,MAAM,2BAA2B,CAAC;AACtE,OAAO,EAAC,KAAK,EAAC,MAAM,oBAAoB,CAAC;AAEzC,OAAO,EAAC,QAAQ,EAAC,MAAM,uBAAuB,CAAC;AAE/C,OAAO,EACL,eAAe,EACf,eAAe,EACf,qBAAqB,EACrB,mBAAmB,EACnB,sBAAsB,GACvB,MAAM,2BAA2B,CAAC;AACnC,OAAO,EACL,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAChB,gBAAgB,GACjB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,EAAC,YAAY,EAAE,gBAAgB,EAAC,MAAM,2BAA2B,CAAC;AAEzE,sBAAsB;AACtB,OAAO,EAAC,QAAQ,EAAC,MAAM,uBAAuB,CAAC;AAM/C,+BAA+B;AAC/B,OAAO,EAAC,UAAU,EAAE,UAAU,EAAC,MAAM,yBAAyB,CAAC;AAG/D,OAAO,EAAC,YAAY,EAAE,YAAY,EAAC,MAAM,2BAA2B,CAAC;AAGrE,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AACzD,OAAO,EAAC,aAAa,EAAC,MAAM,4BAA4B,CAAC;AAGzD,8CAA8C;AAC9C,OAAO,EAAC,cAAc,EAAC,MAAM,iCAAiC,CAAC;AAE/D,OAAO,EAAC,IAAI,EAAC,MAAM,uBAAuB,CAAC;AAe3C,sEAAsE;AACtE,OAAO,EACL,cAAc,EACd,WAAW,GACZ,MAAM,oCAAoC,CAAC;AAC5C,OAAO,EACL,cAAc,EACd,iBAAiB,GAClB,MAAM,gCAAgC,CAAC"}

package/lib/esm/interfaces/IDataset.d.ts

@@ -1,5 +1,6 @@
 import type { SelectQuery } from '../queries/SelectQuery.js';
 import type { AskQuery } from '../queries/AskQuery.js';
+import type { CountQuery } from '../queries/CountQuery.js';
 import type { CreateQuery } from '../queries/CreateQuery.js';
 import type { UpdateQuery } from '../queries/UpdateQuery.js';
 import type { DeleteQuery, DeleteResponse } from '../queries/DeleteQuery.js';
@@ -42,6 +43,28 @@ export interface IDataset {
      * API was built to remove.
      */
     askQuery(query: AskQuery): Promise<boolean>;
+    /**
+     * Count the matching instances — a number, not a result set.
+     *
+     * **Optional**, unlike {@link askQuery}. Adding a required method would break
+     * every existing implementer at compile time; `resolveCount` in `queryDispatch`
+     * turns a missing implementation into a precise runtime error instead. Every
+     * store extending {@link SparqlDataset} gets it with no edit.
+     *
+     * A {@link CountQuery} carries a pattern and nothing else: no projection, no
+     * sorting, and in particular no pagination — a count of a windowed query is
+     * meaningless, so the type cannot hold a window. A SPARQL-backed store emits
+     * `SELECT (COUNT(DISTINCT ?s) AS ?count) WHERE { … }`; another backend answers it
+     * however it can. This package contains **no path that rewrites a count as a
+     * select** and measures the array: that would hide an unbounded read behind a
+     * call that looks cheap.
+     *
+     * Must resolve to a real, non-negative integer — a non-number is rejected, not
+     * coerced. Must reject on failure: reporting an unreachable store as `0` renders
+     * an empty table that is indistinguishable from real data, which is the failure
+     * mode this API was built to remove.
+     */
+    countQuery?(query: CountQuery): Promise<number>;
     /**
      * Receives update AND upsert mutations — `lower(query)` yields `kind: 'update'`,
      * `'update_where'` or `'upsert'`. An implementation that does not handle `'upsert'`

package/lib/esm/interfaces/IFileStore.d.ts

@@ -1,4 +1,38 @@
 import type { Readable } from 'stream';
+/**
+ * Options for `IFileStore.saveFile`.
+ *
+ * Passed as the third argument. A plain `string` is still accepted there and is
+ * read as the old positional `mimeType`, so existing callers keep working.
+ */
+export interface SaveFileOptions {
+    /** Content type of the stored bytes, e.g. `image/webp`. */
+    mimeType?: string;
+    /** Cache header the store should attach, e.g. `public, max-age=31536000, immutable`. */
+    cacheControl?: string;
+    /** Store-level user metadata, when the backing store supports it. */
+    metadata?: Record<string, string>;
+    /**
+     * Rename instead of overwriting when the path is already taken.
+     *
+     * Left `undefined` when the caller did not say: each store then applies its
+     * own default (`S3FileStore` overwrites, `LocalFileStore` adds a suffix).
+     */
+    preventDuplicates?: boolean;
+}
+/**
+ * Metadata of a stored file, for verify-after-upload.
+ *
+ * `sha256` is only set when the store can actually report a content hash; a
+ * caller that does not get one must treat the file as "cannot verify" rather
+ * than falling back to `etag`, which is not a content hash on S3.
+ */
+export interface FileStat {
+    size: number;
+    /** Only when the store can report it. */
+    sha256?: string;
+    etag?: string;
+}
 export interface IFileStore {
     /**
      * The base URL to access the filestore's files. For example:
@@ -12,5 +46,34 @@ export interface IFileStore {
     fileExists(filePath: string): Promise<boolean>;
     getFile(filePath: string): Promise<Buffer | null>;
     listFiles(prefix?: string): Promise<string[]>;
-    saveFile(filePath: string, fileContent: string | Uint8Array | Buffer | Readable, mimeType?: string, preventDuplicates?: boolean): Promise<string | null>;
+    saveFile(filePath: string, fileContent: string | Uint8Array | Buffer | Readable, 
+    /** `SaveFileOptions`, or a `string` read as the old positional `mimeType`. */
+    options?: SaveFileOptions | string, 
+    /** Only honoured when `options` is a string; otherwise use `options.preventDuplicates`. */
+    preventDuplicates?: boolean): Promise<string | null>;
+    /**
+     * Optional. Metadata of a stored file, for verify-after-upload.
+     * Resolves to `null` when the file does not exist.
+     *
+     * Optional by design (plan 011 D7): a store without it still publishes, and
+     * the caller simply skips verification.
+     */
+    statFile?(filePath: string): Promise<FileStat | null>;
 }
+/**
+ * Normalise `saveFile`'s widened third argument into a single options object.
+ * Every `IFileStore` implementation should call this first, so the positional
+ * mime-type form and the options form cannot drift apart.
+ *
+ * `preventDuplicates` stays `undefined` when neither `options.preventDuplicates`
+ * nor the positional argument was given: "unspecified" travels end to end and
+ * **each store applies its own default** (`S3FileStore` overwrites,
+ * `LocalFileStore` adds a random suffix). This helper must never invent `false`,
+ * or a two-argument `saveFile(path, bytes)` would silently start overwriting.
+ *
+ * `options.preventDuplicates` wins over the positional argument when both are
+ * given.
+ */
+export declare function normalizeSaveFileOptions(options?: SaveFileOptions | string, preventDuplicates?: boolean): SaveFileOptions & {
+    preventDuplicates?: boolean | undefined;
+};

package/lib/esm/interfaces/IFileStore.js

@@ -1,2 +1,22 @@
-export {};
+/**
+ * Normalise `saveFile`'s widened third argument into a single options object.
+ * Every `IFileStore` implementation should call this first, so the positional
+ * mime-type form and the options form cannot drift apart.
+ *
+ * `preventDuplicates` stays `undefined` when neither `options.preventDuplicates`
+ * nor the positional argument was given: "unspecified" travels end to end and
+ * **each store applies its own default** (`S3FileStore` overwrites,
+ * `LocalFileStore` adds a random suffix). This helper must never invent `false`,
+ * or a two-argument `saveFile(path, bytes)` would silently start overwriting.
+ *
+ * `options.preventDuplicates` wins over the positional argument when both are
+ * given.
+ */
+export function normalizeSaveFileOptions(options, preventDuplicates) {
+    var _a;
+    if (typeof options === 'string') {
+        return { mimeType: options, preventDuplicates };
+    }
+    return Object.assign(Object.assign({}, (options !== null && options !== void 0 ? options : {})), { preventDuplicates: (_a = options === null || options === void 0 ? void 0 : options.preventDuplicates) !== null && _a !== void 0 ? _a : preventDuplicates });
+}
 //# sourceMappingURL=IFileStore.js.map

package/lib/esm/interfaces/IFileStore.js.map

@@ -1 +1 @@
-{"version":3,"file":"IFileStore.js","sourceRoot":"","sources":["../../../src/interfaces/IFileStore.ts"],"names":[],"mappings":""}
+{"version":3,"file":"IFileStore.js","sourceRoot":"","sources":["../../../src/interfaces/IFileStore.ts"],"names":[],"mappings":"AA4EA;;;;;;;;;;;;;GAaG;AACH,MAAM,UAAU,wBAAwB,CACtC,OAAkC,EAClC,iBAA2B;;IAE3B,IAAI,OAAO,OAAO,KAAK,QAAQ,EAAE,CAAC;QAChC,OAAO,EAAC,QAAQ,EAAE,OAAO,EAAE,iBAAiB,EAAC,CAAC;IAChD,CAAC;IACD,uCACK,CAAC,OAAO,aAAP,OAAO,cAAP,OAAO,GAAI,EAAE,CAAC,KAClB,iBAAiB,EAAE,MAAA,OAAO,aAAP,OAAO,uBAAP,OAAO,CAAE,iBAAiB,mCAAI,iBAAiB,IAClE;AACJ,CAAC"}

package/lib/esm/queries/CountBuilder.d.ts

@@ -0,0 +1,69 @@
+/**
+ * `CountBuilder` — a query whose answer is a number.
+ *
+ * A small sibling of `SelectBuilder` rather than a mode of it, for the same reason
+ * {@link AskBuilder} is: it can only hold a pattern (shape, subject(s), where,
+ * minus), so the normalisation a count needs is a property of the *type*. There is
+ * no projection, ordering or **pagination** to drop, because none can be set — and
+ * a count of a windowed query is meaningless, so that is the point.
+ *
+ * Deliberately **non-generic**. `SelectBuilder<S, R, Result>` is heavily inferred;
+ * a count answers `number` no matter what the select's projection was, so this type
+ * takes part in none of that inference and cannot perturb it.
+ */
+import type { ShapeConstructor } from '../shapes/Shape.js';
+import type { WherePath } from './SelectQuery.js';
+import type { RawMinusEntry } from './IRDesugar.js';
+import type { NodeShapeData } from '../shapes/SHACL.js';
+import type { NodeReferenceValue } from './QueryFactory.js';
+import type { IDataset } from '../interfaces/IDataset.js';
+import { PendingQueryContext } from './QueryContext.js';
+import type { CountQuery, CountQueryJSON, RawCountInput } from './CountQuery.js';
+/**
+ * Everything a count can carry. Assembled by `SelectBuilder.toCount()` or
+ * `Shape.count()`.
+ *
+ * `shapeClass` is required — a shapeless count would count every node in the store.
+ */
+export type CountSpec = {
+    shapeClass: ShapeConstructor<any>;
+    subject?: NodeReferenceValue | PendingQueryContext;
+    subjects?: NodeReferenceValue[];
+    where?: WherePath;
+    minusEntries?: RawMinusEntry[];
+    /** `.for(null)` was called — there is no subject to count. */
+    nullSubject?: boolean;
+};
+export declare class CountBuilder implements PromiseLike<number>, Promise<number> {
+    private readonly _spec;
+    private constructor();
+    /** Build from an assembled spec — used by `.toCount()` and `Shape.count()`. */
+    static of(spec: CountSpec): CountBuilder;
+    /** Discriminator for the free `lower()` function and dataset routing. */
+    readonly __queryKind: "count";
+    /** The shape whose matching instances are counted — also the routing key. */
+    get shape(): NodeShapeData;
+    toRawInput(): RawCountInput;
+    toJSON(): CountQueryJSON;
+    static fromJSON(json: CountQueryJSON): CountBuilder;
+    /**
+     * Execute and resolve to a real number.
+     *
+     * **A failure rejects — it is never reported as `0`.** A count of `0` renders an
+     * empty table and is indistinguishable from real data, so a broken count that
+     * answered `0` would hide rather than fail. Do not wrap this in `.catch(() => 0)`.
+     *
+     * The one case that resolves `0` without querying is a query with no subject to
+     * count — `.for(null)`, or a `PendingQueryContext` as the subject that has not
+     * landed: "how many nodes with no id match?" has a correct total answer, and it
+     * is `0`.
+     */
+    exec(target?: IDataset): Promise<number>;
+    /** `await` triggers execution. */
+    then<TResult1 = number, TResult2 = never>(onfulfilled?: ((value: number) => TResult1 | PromiseLike<TResult1>) | null, onrejected?: ((reason: any) => TResult2 | PromiseLike<TResult2>) | null): Promise<TResult1 | TResult2>;
+    catch<TResult = never>(onrejected?: ((reason: any) => TResult | PromiseLike<TResult>) | null): Promise<number | TResult>;
+    finally(onfinally?: (() => void) | null): Promise<number>;
+    get [Symbol.toStringTag](): string;
+}
+/** Narrow an unknown query object to a count. */
+export declare function isCountQuery(query: unknown): query is CountQuery;

package/lib/esm/queries/CountBuilder.js

@@ -0,0 +1,162 @@
+/*
+ * This Source Code Form is subject to the terms of the Mozilla Public
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/.
+ */
+var __awaiter = (this && this.__awaiter) || function (thisArg, _arguments, P, generator) {
+    function adopt(value) { return value instanceof P ? value : new P(function (resolve) { resolve(value); }); }
+    return new (P || (P = Promise))(function (resolve, reject) {
+        function fulfilled(value) { try { step(generator.next(value)); } catch (e) { reject(e); } }
+        function rejected(value) { try { step(generator["throw"](value)); } catch (e) { reject(e); } }
+        function step(result) { result.done ? resolve(result.value) : adopt(result.value).then(fulfilled, rejected); }
+        step((generator = generator.apply(thisArg, _arguments || [])).next());
+    });
+};
+import { resolveShape } from './resolveShape.js';
+import { PendingQueryContext } from './QueryContext.js';
+import { encodeContextRef, isContextRefJSON } from './ContextRef.js';
+import { WIRE_VERSION, assertWireVersion } from './wireVersion.js';
+import { getQueryDispatch, resolveCount } from './queryDispatch.js';
+import { serializeWherePath, serializeRawMinusEntry, deserializeWherePath, deserializeRawMinusEntry, } from './QueryBuilderSerialization.js';
+export class CountBuilder {
+    constructor(spec) {
+        /** Discriminator for the free `lower()` function and dataset routing. */
+        this.__queryKind = 'count';
+        this._spec = spec;
+    }
+    /** Build from an assembled spec — used by `.toCount()` and `Shape.count()`. */
+    static of(spec) {
+        return new CountBuilder(spec);
+    }
+    /** The shape whose matching instances are counted — also the routing key. */
+    get shape() {
+        return this._spec.shapeClass.shape;
+    }
+    toRawInput() {
+        const { shapeClass, subject, subjects, where, minusEntries, nullSubject } = this._spec;
+        const input = { shape: shapeClass };
+        // Carried so lowering can reject it. `exec()` answers `0` before dispatching,
+        // but a store handed the builder directly (e.g. after `fromJSON`) would
+        // otherwise lower a subject-less query that matches every instance of the
+        // shape and report that as the count of one node.
+        if (nullSubject)
+            input.nullSubject = true;
+        if (subject)
+            input.subject = subject;
+        if (subjects && subjects.length > 0)
+            input.subjects = subjects;
+        if (where)
+            input.where = where;
+        if (minusEntries && minusEntries.length > 0)
+            input.minusEntries = minusEntries;
+        return input;
+    }
+    toJSON() {
+        var _a;
+        const { shapeClass, subject, subjects, where, minusEntries, nullSubject } = this._spec;
+        const shapeId = (_a = shapeClass.shape) === null || _a === void 0 ? void 0 : _a.id;
+        if (!shapeId) {
+            // Refuse here rather than emitting `shape: ''` for the receiver's `fromJSON`
+            // to reject: the caller who holds the shape can act on this, and a peer
+            // across a wire cannot.
+            throw new Error('Cannot serialize a count query whose shape has no id. A count envelope must ' +
+                'name a shape — a shapeless count would count every node in the store.');
+        }
+        const json = {
+            v: WIRE_VERSION,
+            op: 'count',
+            shape: shapeId,
+        };
+        if (subject instanceof PendingQueryContext) {
+            // Carry the reference, not its (possibly unresolved) id, so the receiver
+            // resolves it against its own context map at lowering time.
+            json.subject = encodeContextRef(subject.contextName);
+        }
+        else if (subject && typeof subject === 'object' && 'id' in subject) {
+            json.subject = subject.id;
+        }
+        if (subjects && subjects.length > 0) {
+            json.subjects = subjects.map((s) => s.id);
+        }
+        if (where) {
+            json.where = serializeWherePath(where, shapeClass.shape);
+        }
+        if (minusEntries && minusEntries.length > 0) {
+            json.minusEntries = minusEntries.map((e) => serializeRawMinusEntry(e, shapeClass.shape));
+        }
+        if (nullSubject) {
+            json.nullSubject = true;
+        }
+        return json;
+    }
+    static fromJSON(json) {
+        var _a;
+        assertWireVersion(json.v);
+        if (!json.shape) {
+            throw new Error('A count envelope must name a `shape`. A shapeless count would count every ' +
+                'node in the store, under any type or none.');
+        }
+        const shapeClass = resolveShape(json.shape);
+        const spec = { shapeClass };
+        if (json.subject !== undefined) {
+            spec.subject = isContextRefJSON(json.subject)
+                ? new PendingQueryContext(json.subject['@ctx'])
+                : { id: json.subject };
+        }
+        if (json.subjects && json.subjects.length > 0) {
+            spec.subjects = json.subjects.map((id) => ({ id }));
+        }
+        if (json.where) {
+            spec.where = deserializeWherePath(shapeClass.shape, json.where);
+        }
+        if ((_a = json.minusEntries) === null || _a === void 0 ? void 0 : _a.length) {
+            spec.minusEntries = json.minusEntries.map((e) => deserializeRawMinusEntry(shapeClass.shape, e));
+        }
+        if (json.nullSubject)
+            spec.nullSubject = true;
+        return new CountBuilder(spec);
+    }
+    /**
+     * Execute and resolve to a real number.
+     *
+     * **A failure rejects — it is never reported as `0`.** A count of `0` renders an
+     * empty table and is indistinguishable from real data, so a broken count that
+     * answered `0` would hide rather than fail. Do not wrap this in `.catch(() => 0)`.
+     *
+     * The one case that resolves `0` without querying is a query with no subject to
+     * count — `.for(null)`, or a `PendingQueryContext` as the subject that has not
+     * landed: "how many nodes with no id match?" has a correct total answer, and it
+     * is `0`.
+     */
+    exec(target) {
+        return __awaiter(this, void 0, void 0, function* () {
+            const { nullSubject, subject } = this._spec;
+            if (nullSubject)
+                return 0;
+            if (subject instanceof PendingQueryContext && !subject.id)
+                return 0;
+            // `async` ensures a missing global dispatch rejects rather than throwing
+            // synchronously past the caller's `.catch()`.
+            const dispatch = target !== null && target !== void 0 ? target : getQueryDispatch();
+            return resolveCount(dispatch, this);
+        });
+    }
+    /** `await` triggers execution. */
+    then(onfulfilled, onrejected) {
+        return this.exec().then(onfulfilled, onrejected);
+    }
+    catch(onrejected) {
+        return this.then().catch(onrejected);
+    }
+    finally(onfinally) {
+        return this.then().finally(onfinally);
+    }
+    get [Symbol.toStringTag]() {
+        return 'CountBuilder';
+    }
+}
+/** Narrow an unknown query object to a count. */
+export function isCountQuery(query) {
+    return !!query && query.__queryKind === 'count';
+}
+//# sourceMappingURL=CountBuilder.js.map

package/lib/esm/queries/CountBuilder.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"CountBuilder.js","sourceRoot":"","sources":["../../../src/queries/CountBuilder.ts"],"names":[],"mappings":"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"}