@_linked/core 2.18.1 → 2.19.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # Changelog
 
+## 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

@@ -381,7 +381,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 +487,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/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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"}

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

@@ -0,0 +1,80 @@
+/**
+ * The count query — "how many instances match?", answered with a number.
+ *
+ * A count carries a **pattern and nothing else**: no projection, no sorting, no
+ * pagination. Those shape or window a *solution sequence*, and the number a count
+ * answers is a property of the whole match set, not of a page of it — so rather
+ * than being ignored or guarded against, they are simply not expressible here.
+ *
+ * This is the sibling of {@link AskQuery}: same idea, `number` instead of
+ * `boolean`. `SelectBuilder.count()` is the first question asked this way.
+ */
+import type { NodeShapeData } from '../shapes/SHACL.js';
+import type { WherePath } from './SelectQuery.js';
+import type { RawMinusEntry } from './IRDesugar.js';
+import type { NodeReferenceValue } from './QueryFactory.js';
+import type { PendingQueryContext } from './QueryContext.js';
+import type { ContextRefJSON } from './ContextRef.js';
+import type { WherePathJSON, RawMinusEntryJSON } from './QueryBuilderSerialization.js';
+/**
+ * The live, closed (read-only) count query — the object an `IDataset` receives.
+ *
+ * `shape` is **required**, unlike an ask's. A shapeless count would count every
+ * node in the store; there is no useful reading of that, so the type does not
+ * permit it.
+ */
+export interface CountQuery {
+    readonly __queryKind: 'count';
+    /** The shape whose matching instances are counted. Also the routing key. */
+    readonly shape: NodeShapeData;
+    toJSON(): CountQueryJSON;
+    toRawInput(): RawCountInput;
+}
+/** Pre-lowering input, as the builder hands it to `lower()`. */
+export type RawCountInput = {
+    /**
+     * `.for(null)` — no subject to count. Lowering rejects it; `exec()` answers `0`
+     * before dispatching. See `lowerCount`.
+     */
+    nullSubject?: boolean;
+    shape?: {
+        shape?: {
+            id?: string;
+        };
+        id?: string;
+    };
+    subject?: NodeReferenceValue | PendingQueryContext;
+    subjects?: NodeReferenceValue[];
+    where?: WherePath;
+    minusEntries?: RawMinusEntry[];
+};
+/**
+ * The DSL-JSON wire form of a count query.
+ *
+ * Carries `op: 'count'` — the same discriminator ask and mutation envelopes use, so
+ * `fromJSON` routes on it and an older peer rejects an unknown op loudly rather
+ * than reinterpreting the envelope as a select (which would answer with *rows*,
+ * windowed by nothing, where the caller expected a total).
+ *
+ * Every field is pattern-bearing. There is deliberately no `fields`, `limit`,
+ * `offset`, `sortBy` or `one`: a receiver has nothing to validate or ignore.
+ *
+ * ```json
+ * {"v": "1.1", "op": "count",
+ *  "shape": "https://linked.cm/shape/core/Person",
+ *  "where": {"name": "Semmy"}}
+ * ```
+ */
+export type CountQueryJSON = {
+    v?: string;
+    op: 'count';
+    /** Required — see {@link CountQuery.shape}. */
+    shape: string;
+    /** A node id, or a `{@ctx: name}` reference resolved at lowering. */
+    subject?: string | ContextRefJSON;
+    subjects?: string[];
+    where?: WherePathJSON;
+    minusEntries?: RawMinusEntryJSON[];
+    /** `.for(null)` — no subject to count; the answer is `0` without querying. */
+    nullSubject?: boolean;
+};

package/lib/esm/queries/CountQuery.js

@@ -0,0 +1,7 @@
+/*
+ * 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/.
+ */
+export {};
+//# sourceMappingURL=CountQuery.js.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"CountQuery.js","sourceRoot":"","sources":["../../../src/queries/CountQuery.ts"],"names":[],"mappings":"AAAA;;;;GAIG"}

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

@@ -3,7 +3,7 @@ import type { PathExpr } from '../paths/PropertyPathExpr.js';
 export type IRDirection = 'ASC' | 'DESC';
 export type IRAlias = string;
 export type IRValue = string | number | boolean | null;
-export type IRQuery = IRSelectQuery | IRAskQuery | IRCreateMutation | IRUpdateMutation | IRUpsertMutation | IRDeleteMutation | IRDeleteAllMutation | IRDeleteWhereMutation | IRUpdateWhereMutation;
+export type IRQuery = IRSelectQuery | IRAskQuery | IRCountQuery | IRCreateMutation | IRUpdateMutation | IRUpsertMutation | IRDeleteMutation | IRDeleteAllMutation | IRDeleteWhereMutation | IRUpdateWhereMutation;
 export type IRSelectQuery = {
     kind: 'select';
     root: IRShapeScanPattern;
@@ -39,6 +39,36 @@ export type IRAskQuery = {
     subjectId?: string;
     subjectIds?: string[];
 };
+/**
+ * A query whose answer is a single number: how many instances of a shape match.
+ *
+ * Like {@link IRAskQuery}, it carries a **pattern and nothing else**. There is no
+ * `projection`, `orderBy`, `limit` or `offset`: each of those shapes or windows a
+ * *solution sequence*, and a count has none — the number it answers is a property
+ * of the whole match set. So rather than being ignored during conversion, or
+ * guarded against, they are unrepresentable.
+ *
+ * That is the entire reason this is a distinct IR kind and not a flag on
+ * {@link IRSelectQuery}: a count of a windowed query is meaningless, and a type
+ * that cannot hold the window cannot half-drop it.
+ *
+ * `root` is **required**, unlike an ask's. A shapeless count would count every
+ * node in the store, which is never what a caller means.
+ */
+export type IRCountQuery = {
+    kind: 'count';
+    root: IRShapeScanPattern;
+    patterns: IRGraphPattern[];
+    where?: IRExpression;
+    subjectId?: string;
+    subjectIds?: string[];
+    /**
+     * The variable the `COUNT` is bound to (`(COUNT(DISTINCT ?a0) AS ?count)`).
+     * Carried in the IR rather than hardcoded in two places so lowering and result
+     * mapping cannot disagree about it.
+     */
+    alias: IRAlias;
+};
 export type IRProjectionItem = {
     alias: IRAlias;
     expression: IRExpression;

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

@@ -1,6 +1,7 @@
 import { Shape, type ShapeConstructor } from '../shapes/Shape.js';
 import { type QueryBuildFn, type WhereClause, type QueryResponseToResultType, type SelectAllQueryResponse, type QueryComponentLike } from './SelectQuery.js';
 import type { RawSelectInput } from './IRDesugar.js';
+import { CountBuilder } from './CountBuilder.js';
 import type { IDataset } from '../interfaces/IDataset.js';
 import type { NodeShapeData } from '../shapes/SHACL.js';
 import type { NodeReferenceValue } from './QueryFactory.js';
@@ -156,6 +157,85 @@ export declare class SelectBuilder<S extends Shape = Shape, R = any, Result = an
      * @param target Optional explicit dataset, as for {@link exec}.
      */
     exists(target?: IDataset): Promise<boolean>;
+    /**
+     * **How many** rows match this query — the total of the match set, as a real
+     * `number`.
+     *
+     * ```ts
+     * await Person.select().where(p => p.name.equals('Semmy')).count(); // number
+     * await SelectBuilder.from(shapeIri).where(…).count();              // from an IRI alone
+     * ```
+     *
+     * ### The query is normalised to its cheapest correct form first
+     *
+     * **Dropped** — the projection, preloads, sorting *and pagination*
+     * (`limit`/`offset`). **Kept** — filters, `minus` entries and the subject: those
+     * decide membership of the match set. Against a SPARQL store that goes out as:
+     *
+     * ```sparql
+     * SELECT (COUNT(DISTINCT ?a0) AS ?count)
+     * WHERE { ?a0 rdf:type <…> . ?a0 <…name> ?a0_name . FILTER(?a0_name = "Semmy") }
+     * ```
+     *
+     * ### `limit`/`offset` are dropped, not rejected
+     *
+     * A count of a windowed query is meaningless — `OFFSET` skips rows of a *solution
+     * sequence*, and the number a count answers is a property of the whole match set,
+     * not of a page of it. So `.limit(20).offset(40).count()` costs, and answers,
+     * exactly the same as a bare `.count()`.
+     *
+     * Dropping rather than throwing is deliberate: the paging caller holds **one**
+     * builder and wants the page *and* its total from the same filter, so rejecting
+     * the combination would force it to rebuild the builder by hand for no
+     * correctness gain. There is exactly one sensible reading, and it is this one.
+     * `.exists()` already made the same call, so the DSL has one rule — *a
+     * scalar-answering query drops the solution-sequence modifiers* — not two.
+     *
+     * Nor is the drop merely a convention: a {@link CountBuilder} has nowhere to hold
+     * a window, so it cannot be forgotten or half-applied downstream.
+     *
+     * `DISTINCT` is likewise not optional. A filter on a multi-valued property yields
+     * several rows per subject, so the count is of distinct subjects — "how many
+     * instances match", which is the question asked.
+     *
+     * ### Errors are not swallowed
+     *
+     * A store, transport or lowering failure **rejects**; it is never reported as `0`.
+     * `0` is a plausible count: it renders an empty table and looks like data. 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)`, `.for(undefined)`, or an unresolved `PendingQueryContext`
+     * *as the subject*.
+     *
+     * @param target Optional explicit dataset, as for {@link exec}.
+     */
+    count(target?: IDataset): Promise<number>;
+    /**
+     * Reduce this select to the count query that answers "how many match?".
+     *
+     * Public, unlike the ask equivalent, because a caller may want to **forward**
+     * rather than execute: `builder.toCount().toJSON()` is the `{op: 'count'}` wire
+     * envelope a router or RPC boundary sends on, and `fromJSON` turns it back into a
+     * `CountBuilder` on the other side.
+     *
+     * Only the pattern survives — shape, subject(s), filters, `minus`. The projection,
+     * preloads, sorting and pagination are not so much "dropped" as unrepresentable:
+     * {@link CountBuilder} has nowhere to put them. That is the point of it being a
+     * separate builder rather than a mode of this one.
+     */
+    toCount(): CountBuilder;
+    /**
+     * The pattern-bearing part of this select: shape-membership, subject(s), filters
+     * and `minus` — everything that decides which nodes are in the match set, and
+     * nothing that shapes or windows the rows describing them.
+     *
+     * Shared by {@link _toAsk} and {@link toCount} rather than written twice. That is
+     * not only about duplication: if the two normalisations drifted, `.exists()` and
+     * `.count()` would disagree about what the match set *is* — a count of 0 next to
+     * an `exists` of `true`, from the same builder.
+     */
+    private _patternSpec;
     /**
      * Reduce this select to the ask query that answers the same existence question.
      *