@_linked/core 2.25.0 → 2.27.0

package/CHANGELOG.md

@@ -1,5 +1,54 @@
 # Changelog
 
+## 2.27.0
+
+### Minor Changes
+
+- [#311](https://github.com/linked-fw/core/pull/311) [`f397a2e`](https://github.com/linked-fw/core/commit/f397a2e2dfa915b1fd1a0188323e0575941e61b9) Thanks [@flyon](https://github.com/flyon)! - Live queries: `query.live()` on select, count and ask builders returns a handle that keeps its result current — subscribe, await the first result, refresh, patch, close — backed by a framework-free `LiveQueryStore` in core (`@_linked/core/live`, registered automatically by the package root).
+  
+  - Automatic refetching: every local mutation (including `exec(target)`) is observed through the new `subscribeQueryDispatch(listener)`; a dataset may report changes made elsewhere through the optional `IDataset.subscribeChanges(listener)` (and `authoritativeChanges` to defer refetches to its own confirmation); application code can `publishChange(event)`; `invalidate(Shape | iri | {id} | query)` is the manual lever. `LinkedStorage.onRoutingChanged(listener)` lets the store pick up feeds of datasets registered later.
+  - Two helpers describe what queries read and mutations write in predicate IRIs: `queryDependencies(query)` (`narrow`, `filter`, `hidden`, `shapes`, `unbound`) and `mutationEffects(mutation, result?)` (`op`, `shape`, `props`, `ids?`, `membership`). The matcher uses them to refetch by node id where it can, template-wide where it must, scoped by shape.
+  - `LinkedStorage.setDefaultDataset` / `setDatasetForShapes` / `unsetDatasetForShape` now notify `onRoutingChanged` listeners; the live store uses this to reset its cache on a storage change. `QueryDispatchEvent` carries the explicit `target` of an `exec(target)` call. Errors thrown by query-context listeners are now isolated (logged, not propagated).
+  - `findPropertyShapeById` is now exported from `shapes/nodeShapeData` (moved from the SPARQL layer; behaviour unchanged).
+  
+  All additions are backwards compatible; `await query` and the mutation API are unchanged.
+
+## 2.26.0
+
+### Minor Changes
+
+- [#308](https://github.com/linked-fw/core/pull/308) [`5f27582`](https://github.com/linked-fw/core/commit/5f27582cb3f341927a70a3c06279764f35cf4e4c) Thanks [@flyon](https://github.com/flyon)! - Add helpers for relation properties declared with `sh:class` alone, so callers can find the shape a relation's values go through.
+  
+  New in `@_linked/core/utils/ShapeClass`:
+  
+  - `getTargetClassId(shape, shapes?)`: the class a shape's instances are typed with. It returns the shape's own `targetClass`, or else the first one it finds through `extends`, or `undefined`. It accepts a shape IRI, a `{id}`, shape data or wire metadata, or a shape class, and it never throws.
+  - `getShapesForTargetClass(classIri, shapes?)`: the least specific shapes whose own or inherited `targetClass` is exactly `classIri`, sorted by id. A shape that extends another match is left out. If an `extends` cycle would leave out every match, all matches are kept.
+  
+  New module `@_linked/core/shapes/relationShape`:
+  
+  - `isRelation(property)`: true when the property has `sh:node`, has `sh:class`, or has an IRI or blank-node `sh:nodeKind`.
+  - `rangeClassOf(property, shapes?)`: the declared `sh:class`, or else the `targetClass` of the property's `sh:node` shape.
+  - `resolveRelationShape(property, shapes?)`: returns `{shapeId?, candidates, source: 'node' | 'class' | 'none'}`. A declared `sh:node` always wins. Otherwise the shapes from `getShapesForTargetClass` are the candidates, and the first one is used. If more than one unrelated root qualifies, it logs one warning per class and candidate set.
+  
+  Pass `shapes` (for example, an app's own shape catalog) to resolve among that set. Without it, lookups use the shape registry.
+  
+  ```ts
+  import {getTargetClassId, getShapesForTargetClass} from '@_linked/core/utils/ShapeClass';
+  import {isRelation, resolveRelationShape} from '@_linked/core/shapes/relationShape';
+  
+  getTargetClassId('https://example.org/shapes/Employee'); // inherited through extends
+  getShapesForTargetClass('https://schema.org/Person', catalog); // the root shapes only
+  
+  if (isRelation(property)) {
+    const {shapeId, source} = resolveRelationShape(property, catalog);
+    // shapeId is undefined when no shape targets the class
+  }
+  ```
+  
+  A relation never upgrades itself to a sub-shape. Suppose `Person` and `Employee extends Person` both target `schema:Person`. A `sh:class schema:Person` relation then resolves to `Person`, with no warning. To use `Employee`, declare `sh:node`.
+  
+  **Behaviour change:** validation now treats a property with `sh:class` as node-valued, the same way it treats one with `sh:node`. Creates and updates are validated, so a write that passes a bare literal (such as a string) for a `sh:class` property is now rejected. Pass a reference (`{id}`) instead.
+
 ## 2.25.0
 
 ### Minor Changes

package/README.md

@@ -42,6 +42,7 @@ npm run setup
 - **[DSL-JSON — the Linked query wire format](./documentation/dsl-json.md)** — the canonical, standardized query structure.
 - [Intermediate Representation (IR)](./documentation/intermediate-representation.md) — the internal algebra the SPARQL dataset lowers to.
 - [SPARQL Algebra Layer](./documentation/sparql-algebra.md)
+- [Live queries](./documentation/live-queries.md) — `query.live()`, change sources, and what triggers a refetch.
 
 ## How Linked works — from shapes to query results
 
@@ -1132,6 +1133,32 @@ yet — it travels as a `{$ctx}` marker and is resolved wherever the query is fi
 `FieldSet` serializes the same way (`FieldSet.for(Person, ['name','knows']).toJSON()` /
 `FieldSet.fromJSON(json)`).
 
+## Live queries
+
+A live query keeps its result current: subscribe once, and whenever something changes that the query
+can have read — a local mutation, a change reported by a dataset's feed, or one you publish yourself —
+it fetches again and notifies its listeners. The store is framework-free and lives in core; UI
+bindings such as `@_linked/react` sit on top of it. Full guide: **[documentation/live-queries.md](./documentation/live-queries.md)**.
+
+```typescript
+const live = Team.select((t) => [t.name, t.members.size()]).for({id: teamId}).live();
+const first = await live;                       // first data; the handle stays live
+live.subscribe((state) => render(state.data));  // every later result
+live.close();
+
+Team.select().toCount().live((s) => setTotal(s.data)); // listener shorthand; counts and asks go live too
+
+await Team.update({members: {add: [{id: personId}]}}).for({id: teamId});
+// → every live query that reads this team's members refetches; unrelated ones do not.
+```
+
+- `queryDependencies(query)` and `mutationEffects(mutation, result?)` describe, in predicate IRIs, what a
+  query reads and what a mutation writes; the store matches the two (by node id where it can, template-wide
+  where it must, scoped by shape).
+- `subscribeQueryDispatch(listener)` observes every query that runs through the dispatch, `exec(target)` included.
+- A dataset can report changes made elsewhere through the optional `IDataset.subscribeChanges(listener)`;
+  `publishChange(event)` does the same from application code; `invalidate(Shape | {id} | query)` is the manual lever.
+
 ## TODO
 
 - Allow `preloadFor` to accept another query (not just a component).

package/lib/esm/index.d.ts

@@ -1,4 +1,5 @@
 import './shapes/index.js';
+import './live.js';
 export { syncShapes, syncShape } from './shapes/syncShapes.js';
 export { rdfList } from './shapes/List.js';
 export { serializePathToNodeData } from './shapes/serializePathToNodeData.js';
@@ -12,6 +13,8 @@ export type { LowerableQuery } from './queries/lower.js';
 export { fromJSON } from './queries/fromJSON.js';
 export type { QueryJSON } from './queries/fromJSON.js';
 export { getQueryContext, setQueryContext, subscribeQueryContext, PendingQueryContext, UnresolvedContextError, } from './queries/QueryContext.js';
+export { subscribeQueryDispatch } from './queries/queryDispatch.js';
+export type { QueryDispatchEvent, QueryDispatchListener } from './queries/queryDispatch.js';
 export { CONTEXT_REF_KEY, encodeContextRef, isContextRefJSON, resolveContextId, } from './queries/ContextRef.js';
 export type { ContextRefJSON } from './queries/ContextRef.js';
 export { PropertyPath, walkPropertyPath } from './queries/PropertyPath.js';
@@ -36,3 +39,9 @@ export type { LinkedComponentInterface, QueryComponentLike } from './queries/Sel
 export { encodeNodeData, encodeValue, } from './queries/MutationSerialization.js';
 export { decodeNodeData, lowerMutationJSON, } from './queries/lowerMutationJSON.js';
 export type { MutationJSON, CreateMutationJSON, UpdateMutationJSON, DeleteMutationJSON, MutationValueJSON, MutationNodeDataJSON, } from './queries/MutationSerialization.js';
+export { queryDependencies, mutationEffects } from './queries/queryDependencies.js';
+export type { QueryDependencies, MutationEffects } from './queries/queryDependencies.js';
+export { findPropertyShapeById } from './shapes/nodeShapeData.js';
+export { LiveQueryStore, getLiveQueryStore, resetLiveQueryStore, publishChange, invalidate } from './live/LiveQueryStore.js';
+export type { ChangeEvent } from './live/changes.js';
+export type { LiveQuery, LiveState, LiveStatus, LiveListener, LiveQueryOptions, LiveQueryStoreOptions, } from './live/LiveQueryStore.js';

package/lib/esm/index.js

@@ -5,6 +5,8 @@
  */
 // Registers every shape core defines (side effects only).
 import './shapes/index.js';
+// Registers the live-query store so `query.live()` works (side effects only).
+import './live.js';
 export { syncShapes, syncShape } from './shapes/syncShapes.js';
 export { rdfList } from './shapes/List.js';
 export { serializePathToNodeData } from './shapes/serializePathToNodeData.js';
@@ -18,6 +20,7 @@ export { SelectBuilder, QueryBuilder } from './queries/QueryBuilder.js';
 export { lower } from './queries/lower.js';
 export { fromJSON } from './queries/fromJSON.js';
 export { getQueryContext, setQueryContext, subscribeQueryContext, PendingQueryContext, UnresolvedContextError, } from './queries/QueryContext.js';
+export { subscribeQueryDispatch } from './queries/queryDispatch.js';
 export { CONTEXT_REF_KEY, encodeContextRef, isContextRefJSON, resolveContextId, } from './queries/ContextRef.js';
 export { PropertyPath, walkPropertyPath } from './queries/PropertyPath.js';
 // Phase 3a — FieldSet
@@ -34,4 +37,9 @@ export { Expr } from './expressions/Expr.js';
 // Mutation DSL-JSON serialization (create/update/delete to/from JSON)
 export { encodeNodeData, encodeValue, } from './queries/MutationSerialization.js';
 export { decodeNodeData, lowerMutationJSON, } from './queries/lowerMutationJSON.js';
+// Live-query dependency helpers — what a query reads and a mutation writes, as predicates
+export { queryDependencies, mutationEffects } from './queries/queryDependencies.js';
+export { findPropertyShapeById } from './shapes/nodeShapeData.js';
+// Live queries — see documentation/live-queries.md
+export { LiveQueryStore, getLiveQueryStore, resetLiveQueryStore, publishChange, invalidate } from './live/LiveQueryStore.js';
 //# sourceMappingURL=index.js.map

package/lib/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,0DAA0D;AAC1D,OAAO,mBAAmB,CAAC;AAC3B,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","sourcesContent":["/*\n * This Source Code Form is subject to the terms of the Mozilla Public\n * License, v. 2.0. If a copy of the MPL was not distributed with this\n * file, You can obtain one at https://mozilla.org/MPL/2.0/.\n */\n// Registers every shape core defines (side effects only).\nimport './shapes/index.js';\nexport {syncShapes, syncShape} from './shapes/syncShapes.js';\nexport {rdfList} from './shapes/List.js';\nexport {serializePathToNodeData} from './shapes/serializePathToNodeData.js';\n// Core public API surface (documented as root imports in the README).\nexport {Shape} from './shapes/Shape.js';\n// SHACL-aligned validation of plain data objects against a shape.\nexport {validate, assertValid, ShapeValidationError} from './shapes/validation.js';\nexport type {\n  ValidationReport,\n  ValidationResult,\n  ValidationMode,\n  ValidateOptions,\n  ValidatableShape,\n} from './shapes/validation.js';\nexport {LinkedStorage} from './utils/LinkedStorage.js';\n// New dynamic query building API (Phase 2)\nexport {SelectBuilder, QueryBuilder} from './queries/QueryBuilder.js';\nexport {lower} from './queries/lower.js';\nexport type {LowerableQuery} from './queries/lower.js';\nexport {fromJSON} from './queries/fromJSON.js';\nexport type {QueryJSON} from './queries/fromJSON.js';\nexport {\n  getQueryContext,\n  setQueryContext,\n  subscribeQueryContext,\n  PendingQueryContext,\n  UnresolvedContextError,\n} from './queries/QueryContext.js';\nexport {\n  CONTEXT_REF_KEY,\n  encodeContextRef,\n  isContextRefJSON,\n  resolveContextId,\n} from './queries/ContextRef.js';\nexport type {ContextRefJSON} from './queries/ContextRef.js';\nexport {PropertyPath, walkPropertyPath} from './queries/PropertyPath.js';\n\n// Phase 3a — FieldSet\nexport {FieldSet} from './queries/FieldSet.js';\nexport type {FieldSetEntry, FieldSetInput, FieldSetJSON, FieldSetFieldJSON} from './queries/FieldSet.js';\n\n// Phase 4 — Serialization types\nexport type {QueryBuilderJSON} from './queries/QueryBuilder.js';\n\n// Phase 3b — Mutation builders\nexport {AskBuilder, isAskQuery} from './queries/AskBuilder.js';\nexport type {AskSpec} from './queries/AskBuilder.js';\nexport type {AskQuery, AskQueryJSON, RawAskInput} from './queries/AskQuery.js';\nexport {CountBuilder, isCountQuery} from './queries/CountBuilder.js';\nexport type {CountSpec} from './queries/CountBuilder.js';\nexport type {CountQuery, CountQueryJSON, RawCountInput} from './queries/CountQuery.js';\nexport {CreateBuilder} from './queries/CreateBuilder.js';\nexport {UpdateBuilder} from './queries/UpdateBuilder.js';\nexport {DeleteBuilder} from './queries/DeleteBuilder.js';\nexport type {DeleteId} from './queries/DeleteBuilder.js';\n\n// Expressions — computed fields and functions\nexport {ExpressionNode} from './expressions/ExpressionNode.js';\nexport type {ExpressionInput, PropertyRefMap} from './expressions/ExpressionNode.js';\nexport {Expr} from './expressions/Expr.js';\nexport type {\n  ExpressionUpdateProxy,\n  ExpressionUpdateResult,\n  BaseExpressionMethods,\n  NumericExpressionMethods,\n  StringExpressionMethods,\n  DateExpressionMethods,\n  BooleanExpressionMethods,\n} from './expressions/ExpressionMethods.js';\n\n// Phase 5 — Component query integration\nexport type {LinkedComponentInterface, QueryComponentLike} from './queries/SelectQuery.js';\n\n\n// Mutation DSL-JSON serialization (create/update/delete to/from JSON)\nexport {\n  encodeNodeData,\n  encodeValue,\n} from './queries/MutationSerialization.js';\nexport {\n  decodeNodeData,\n  lowerMutationJSON,\n} from './queries/lowerMutationJSON.js';\nexport type {\n  MutationJSON,\n  CreateMutationJSON,\n  UpdateMutationJSON,\n  DeleteMutationJSON,\n  MutationValueJSON,\n  MutationNodeDataJSON,\n} from './queries/MutationSerialization.js';\n\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,0DAA0D;AAC1D,OAAO,mBAAmB,CAAC;AAC3B,8EAA8E;AAC9E,OAAO,WAAW,CAAC;AACnB,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,EAAC,sBAAsB,EAAC,MAAM,4BAA4B,CAAC;AAElE,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;AAWxC,0FAA0F;AAC1F,OAAO,EAAC,iBAAiB,EAAE,eAAe,EAAC,MAAM,gCAAgC,CAAC;AAElF,OAAO,EAAC,qBAAqB,EAAC,MAAM,2BAA2B,CAAC;AAEhE,mDAAmD;AACnD,OAAO,EAAC,cAAc,EAAE,iBAAiB,EAAE,mBAAmB,EAAE,aAAa,EAAE,UAAU,EAAC,MAAM,0BAA0B,CAAC","sourcesContent":["/*\n * This Source Code Form is subject to the terms of the Mozilla Public\n * License, v. 2.0. If a copy of the MPL was not distributed with this\n * file, You can obtain one at https://mozilla.org/MPL/2.0/.\n */\n// Registers every shape core defines (side effects only).\nimport './shapes/index.js';\n// Registers the live-query store so `query.live()` works (side effects only).\nimport './live.js';\nexport {syncShapes, syncShape} from './shapes/syncShapes.js';\nexport {rdfList} from './shapes/List.js';\nexport {serializePathToNodeData} from './shapes/serializePathToNodeData.js';\n// Core public API surface (documented as root imports in the README).\nexport {Shape} from './shapes/Shape.js';\n// SHACL-aligned validation of plain data objects against a shape.\nexport {validate, assertValid, ShapeValidationError} from './shapes/validation.js';\nexport type {\n  ValidationReport,\n  ValidationResult,\n  ValidationMode,\n  ValidateOptions,\n  ValidatableShape,\n} from './shapes/validation.js';\nexport {LinkedStorage} from './utils/LinkedStorage.js';\n// New dynamic query building API (Phase 2)\nexport {SelectBuilder, QueryBuilder} from './queries/QueryBuilder.js';\nexport {lower} from './queries/lower.js';\nexport type {LowerableQuery} from './queries/lower.js';\nexport {fromJSON} from './queries/fromJSON.js';\nexport type {QueryJSON} from './queries/fromJSON.js';\nexport {\n  getQueryContext,\n  setQueryContext,\n  subscribeQueryContext,\n  PendingQueryContext,\n  UnresolvedContextError,\n} from './queries/QueryContext.js';\nexport {subscribeQueryDispatch} from './queries/queryDispatch.js';\nexport type {QueryDispatchEvent, QueryDispatchListener} from './queries/queryDispatch.js';\nexport {\n  CONTEXT_REF_KEY,\n  encodeContextRef,\n  isContextRefJSON,\n  resolveContextId,\n} from './queries/ContextRef.js';\nexport type {ContextRefJSON} from './queries/ContextRef.js';\nexport {PropertyPath, walkPropertyPath} from './queries/PropertyPath.js';\n\n// Phase 3a — FieldSet\nexport {FieldSet} from './queries/FieldSet.js';\nexport type {FieldSetEntry, FieldSetInput, FieldSetJSON, FieldSetFieldJSON} from './queries/FieldSet.js';\n\n// Phase 4 — Serialization types\nexport type {QueryBuilderJSON} from './queries/QueryBuilder.js';\n\n// Phase 3b — Mutation builders\nexport {AskBuilder, isAskQuery} from './queries/AskBuilder.js';\nexport type {AskSpec} from './queries/AskBuilder.js';\nexport type {AskQuery, AskQueryJSON, RawAskInput} from './queries/AskQuery.js';\nexport {CountBuilder, isCountQuery} from './queries/CountBuilder.js';\nexport type {CountSpec} from './queries/CountBuilder.js';\nexport type {CountQuery, CountQueryJSON, RawCountInput} from './queries/CountQuery.js';\nexport {CreateBuilder} from './queries/CreateBuilder.js';\nexport {UpdateBuilder} from './queries/UpdateBuilder.js';\nexport {DeleteBuilder} from './queries/DeleteBuilder.js';\nexport type {DeleteId} from './queries/DeleteBuilder.js';\n\n// Expressions — computed fields and functions\nexport {ExpressionNode} from './expressions/ExpressionNode.js';\nexport type {ExpressionInput, PropertyRefMap} from './expressions/ExpressionNode.js';\nexport {Expr} from './expressions/Expr.js';\nexport type {\n  ExpressionUpdateProxy,\n  ExpressionUpdateResult,\n  BaseExpressionMethods,\n  NumericExpressionMethods,\n  StringExpressionMethods,\n  DateExpressionMethods,\n  BooleanExpressionMethods,\n} from './expressions/ExpressionMethods.js';\n\n// Phase 5 — Component query integration\nexport type {LinkedComponentInterface, QueryComponentLike} from './queries/SelectQuery.js';\n\n\n// Mutation DSL-JSON serialization (create/update/delete to/from JSON)\nexport {\n  encodeNodeData,\n  encodeValue,\n} from './queries/MutationSerialization.js';\nexport {\n  decodeNodeData,\n  lowerMutationJSON,\n} from './queries/lowerMutationJSON.js';\nexport type {\n  MutationJSON,\n  CreateMutationJSON,\n  UpdateMutationJSON,\n  DeleteMutationJSON,\n  MutationValueJSON,\n  MutationNodeDataJSON,\n} from './queries/MutationSerialization.js';\n\n\n// Live-query dependency helpers — what a query reads and a mutation writes, as predicates\nexport {queryDependencies, mutationEffects} from './queries/queryDependencies.js';\nexport type {QueryDependencies, MutationEffects} from './queries/queryDependencies.js';\nexport {findPropertyShapeById} from './shapes/nodeShapeData.js';\n\n// Live queries — see documentation/live-queries.md\nexport {LiveQueryStore, getLiveQueryStore, resetLiveQueryStore, publishChange, invalidate} from './live/LiveQueryStore.js';\nexport type {ChangeEvent} from './live/changes.js';\nexport type {\n  LiveQuery,\n  LiveState,\n  LiveStatus,\n  LiveListener,\n  LiveQueryOptions,\n  LiveQueryStoreOptions,\n} from './live/LiveQueryStore.js';\n"]}

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

@@ -5,6 +5,7 @@ import type { CreateQuery } from '../queries/CreateQuery.js';
 import type { UpdateQuery } from '../queries/UpdateQuery.js';
 import type { DeleteQuery, DeleteResponse } from '../queries/DeleteQuery.js';
 import type { SelectResult, CreateResult, UpdateResult } from '../queries/IntermediateRepresentation.js';
+import type { ChangeEvent } from '../live/changes.js';
 /**
  * Universal dataset interface. Every dataset in the Linked framework accepts
  * Linked Queries as input. The implementing class decides how to handle them —
@@ -74,4 +75,18 @@ export interface IDataset {
     updateQuery?(query: UpdateQuery): Promise<UpdateResult>;
     createQuery?(query: CreateQuery): Promise<CreateResult>;
     deleteQuery?(query: DeleteQuery): Promise<DeleteResponse>;
+    /**
+     * Optional change feed. A dataset that learns about changes made elsewhere
+     * (another client, a server-side job) reports them here as
+     * {@link ChangeEvent}s — the mutation's DSL-JSON plus its result, or
+     * precomputed effects — and the live-query store refetches whatever those
+     * changes can have touched. Returns the unsubscribe function.
+     */
+    subscribeChanges?(listener: (event: ChangeEvent) => void): () => void;
+    /**
+     * When `true`, a local mutation routed to this dataset does not trigger
+     * refetches by itself; the store waits for the dataset's own change event
+     * (the server's confirmation). Only meaningful with `subscribeChanges`.
+     */
+    readonly authoritativeChanges?: boolean;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"IDataset.js","sourceRoot":"","sources":["../../../src/interfaces/IDataset.ts"],"names":[],"mappings":"","sourcesContent":["import type {SelectQuery} from '../queries/SelectQuery.js';\nimport type {AskQuery} from '../queries/AskQuery.js';\nimport type {CountQuery} from '../queries/CountQuery.js';\nimport type {CreateQuery} from '../queries/CreateQuery.js';\nimport type {UpdateQuery} from '../queries/UpdateQuery.js';\nimport type {DeleteQuery, DeleteResponse} from '../queries/DeleteQuery.js';\nimport type {\n  SelectResult,\n  CreateResult,\n  UpdateResult,\n} from '../queries/IntermediateRepresentation.js';\n\n/**\n * Universal dataset interface. Every dataset in the Linked framework accepts\n * Linked Queries as input. The implementing class decides how to handle them —\n * compiling to SPARQL for Fuseki, forwarding as-is to a Host Agent API, etc.\n *\n * Each method receives the live, closed (read-only) query object — the builder\n * viewed through its `*Query` interface — and returns the result. A store reads\n * `query.toJSON()` to forward it, or `lower(query)` to get canonical IR. The\n * calling layer (LinkedStorage via queryDispatch) threads the precise DSL-level\n * TypeScript result type back to the caller.\n */\nexport interface IDataset {\n  /**\n   * Prepares the store to be used.\n   */\n  init?(): Promise<any>;\n\n  /**\n   * Answer a select query — **and a count query**, which arrives here too.\n   *\n   * A count is not a query form of its own the way an ask is. An ask is\n   * `ASK WHERE { … }`; a count is `SELECT (COUNT(DISTINCT ?s) AS ?count) WHERE { … }`\n   * — a select with an aggregate projection, over the same transport, answered with\n   * the same result-set response. Giving it a method of its own meant every router\n   * had to grow an arm for it, and any that did not silently could not count.\n   *\n   * So a store that wants to answer counts branches on the lowered IR:\n   * `lower(query).kind === 'count'` (see {@link CountQuery} and `SparqlDataset`).\n   * A store that does not is no worse off than before — it will fail loudly at the\n   * dispatch (`resolveCount`), which refuses anything but a non-negative integer.\n   * There is deliberately **no path in this package that rewrites a count as a row\n   * query** and measures the array: that would hide an unbounded read behind a call\n   * that looks cheap.\n   *\n   * A count must be answered with a real, non-negative integer, and must reject on\n   * failure: reporting an unreachable store as `0` renders an empty table that is\n   * indistinguishable from real data, which is the failure mode this API was built\n   * to remove.\n   */\n  selectQuery(query: SelectQuery | CountQuery): Promise<SelectResult | number>;\n  /**\n   * Answer an ask query — a boolean, not a result set.\n   *\n   * **Required.** An {@link AskQuery} carries a pattern and nothing else: no\n   * projection, no sorting, no pagination. A SPARQL-backed store emits\n   * `ASK WHERE { … }`; another backend answers it however it can.\n   *\n   * It is required rather than optional, and this package contains **no path that\n   * rewrites an ask as a select**. A store that has no boolean primitive decides\n   * for itself how to answer — that decision belongs to the store, and defaulting\n   * it here would hide it.\n   *\n   * `query.shape` is optional: absent means no `rdf:type` constraint at all\n   * (\"does a node with this IRI exist\"), which lowers to `ASK { <iri> ?p ?o }`.\n   *\n   * Must resolve to a real boolean — a non-boolean is rejected, not coerced,\n   * since a truthy value would silently read as \"exists\". Must reject on\n   * failure: reporting an unreachable store as `false` is the failure mode this\n   * API was built to remove.\n   */\n  askQuery(query: AskQuery): Promise<boolean>;\n  /**\n   * Receives update AND upsert mutations — `lower(query)` yields `kind: 'update'`,\n   * `'update_where'` or `'upsert'`. An implementation that does not handle `'upsert'`\n   * should throw rather than fall through to the update path: an upsert lowered as a\n   * plain update writes an untyped node and reports success.\n   */\n  updateQuery?(query: UpdateQuery): Promise<UpdateResult>;\n  createQuery?(query: CreateQuery): Promise<CreateResult>;\n  deleteQuery?(query: DeleteQuery): Promise<DeleteResponse>;\n}\n"]}
+{"version":3,"file":"IDataset.js","sourceRoot":"","sources":["../../../src/interfaces/IDataset.ts"],"names":[],"mappings":"","sourcesContent":["import type {SelectQuery} from '../queries/SelectQuery.js';\nimport type {AskQuery} from '../queries/AskQuery.js';\nimport type {CountQuery} from '../queries/CountQuery.js';\nimport type {CreateQuery} from '../queries/CreateQuery.js';\nimport type {UpdateQuery} from '../queries/UpdateQuery.js';\nimport type {DeleteQuery, DeleteResponse} from '../queries/DeleteQuery.js';\nimport type {\n  SelectResult,\n  CreateResult,\n  UpdateResult,\n} from '../queries/IntermediateRepresentation.js';\nimport type {ChangeEvent} from '../live/changes.js';\n\n/**\n * Universal dataset interface. Every dataset in the Linked framework accepts\n * Linked Queries as input. The implementing class decides how to handle them —\n * compiling to SPARQL for Fuseki, forwarding as-is to a Host Agent API, etc.\n *\n * Each method receives the live, closed (read-only) query object — the builder\n * viewed through its `*Query` interface — and returns the result. A store reads\n * `query.toJSON()` to forward it, or `lower(query)` to get canonical IR. The\n * calling layer (LinkedStorage via queryDispatch) threads the precise DSL-level\n * TypeScript result type back to the caller.\n */\nexport interface IDataset {\n  /**\n   * Prepares the store to be used.\n   */\n  init?(): Promise<any>;\n\n  /**\n   * Answer a select query — **and a count query**, which arrives here too.\n   *\n   * A count is not a query form of its own the way an ask is. An ask is\n   * `ASK WHERE { … }`; a count is `SELECT (COUNT(DISTINCT ?s) AS ?count) WHERE { … }`\n   * — a select with an aggregate projection, over the same transport, answered with\n   * the same result-set response. Giving it a method of its own meant every router\n   * had to grow an arm for it, and any that did not silently could not count.\n   *\n   * So a store that wants to answer counts branches on the lowered IR:\n   * `lower(query).kind === 'count'` (see {@link CountQuery} and `SparqlDataset`).\n   * A store that does not is no worse off than before — it will fail loudly at the\n   * dispatch (`resolveCount`), which refuses anything but a non-negative integer.\n   * There is deliberately **no path in this package that rewrites a count as a row\n   * query** and measures the array: that would hide an unbounded read behind a call\n   * that looks cheap.\n   *\n   * A count must be answered with a real, non-negative integer, and must reject on\n   * failure: reporting an unreachable store as `0` renders an empty table that is\n   * indistinguishable from real data, which is the failure mode this API was built\n   * to remove.\n   */\n  selectQuery(query: SelectQuery | CountQuery): Promise<SelectResult | number>;\n  /**\n   * Answer an ask query — a boolean, not a result set.\n   *\n   * **Required.** An {@link AskQuery} carries a pattern and nothing else: no\n   * projection, no sorting, no pagination. A SPARQL-backed store emits\n   * `ASK WHERE { … }`; another backend answers it however it can.\n   *\n   * It is required rather than optional, and this package contains **no path that\n   * rewrites an ask as a select**. A store that has no boolean primitive decides\n   * for itself how to answer — that decision belongs to the store, and defaulting\n   * it here would hide it.\n   *\n   * `query.shape` is optional: absent means no `rdf:type` constraint at all\n   * (\"does a node with this IRI exist\"), which lowers to `ASK { <iri> ?p ?o }`.\n   *\n   * Must resolve to a real boolean — a non-boolean is rejected, not coerced,\n   * since a truthy value would silently read as \"exists\". Must reject on\n   * failure: reporting an unreachable store as `false` is the failure mode this\n   * API was built to remove.\n   */\n  askQuery(query: AskQuery): Promise<boolean>;\n  /**\n   * Receives update AND upsert mutations — `lower(query)` yields `kind: 'update'`,\n   * `'update_where'` or `'upsert'`. An implementation that does not handle `'upsert'`\n   * should throw rather than fall through to the update path: an upsert lowered as a\n   * plain update writes an untyped node and reports success.\n   */\n  updateQuery?(query: UpdateQuery): Promise<UpdateResult>;\n  createQuery?(query: CreateQuery): Promise<CreateResult>;\n  deleteQuery?(query: DeleteQuery): Promise<DeleteResponse>;\n\n  /**\n   * Optional change feed. A dataset that learns about changes made elsewhere\n   * (another client, a server-side job) reports them here as\n   * {@link ChangeEvent}s — the mutation's DSL-JSON plus its result, or\n   * precomputed effects — and the live-query store refetches whatever those\n   * changes can have touched. Returns the unsubscribe function.\n   */\n  subscribeChanges?(listener: (event: ChangeEvent) => void): () => void;\n  /**\n   * When `true`, a local mutation routed to this dataset does not trigger\n   * refetches by itself; the store waits for the dataset's own change event\n   * (the server's confirmation). Only meaningful with `subscribeChanges`.\n   */\n  readonly authoritativeChanges?: boolean;\n}\n"]}

package/lib/esm/live/LiveQueryStore.d.ts

@@ -0,0 +1,240 @@
+import { type MutationEffects, type QueryDependencies } from '../queries/queryDependencies.js';
+import type { ShapeConstructor } from '../shapes/Shape.js';
+import { type ChangeEvent, type ChangeOrigin } from './changes.js';
+import { type InstanceParams, type LiveBuilder, type LiveQueryKind } from './keys.js';
+export type LiveStatus = 'pending' | 'loading' | 'success' | 'error';
+/**
+ * What a live query currently knows.
+ *
+ * - `pending`: nothing requested yet (no storage configured, or the subject is
+ *   a query context that has not been set).
+ * - `loading`: first request in flight, no data yet.
+ * - `success` / `error`: last request settled. On error the previous `data`,
+ *   if any, is kept so a screen does not go blank over a transient failure.
+ * - `refreshing`: a request is in flight while `data` is present.
+ * - `notFound`: a single-subject query answered `null`.
+ *
+ * The object is replaced (never mutated) on every change, so it is safe as a
+ * `useSyncExternalStore` snapshot.
+ */
+export type LiveState<R = unknown> = {
+    status: LiveStatus;
+    data?: R;
+    error?: Error;
+    notFound: boolean;
+    refreshing: boolean;
+};
+export type LiveListener<R = unknown> = (state: LiveState<R>) => void;
+export type LiveQueryOptions = {
+    /** Metadata for the template registry (`prepare()`), not identity. */
+    name?: string;
+    /** `false` opts this template — every query with this exact template — out of automatic invalidation. Default `true`. */
+    reactive?: boolean;
+    /** A pinned template survives having no instances (component definitions, `prepare()`). */
+    pinned?: boolean;
+};
+/**
+ * The handle returned by `query.live()`.
+ *
+ * It is `PromiseLike`: `await live` resolves with the first successful `data`
+ * (or rejects with the first error) and the handle stays live afterwards. It
+ * waits for as long as storage is not configured or a pending query context is
+ * not set. Because the handle is thenable, do not `return` it from an `async`
+ * function — the promise machinery would unwrap it. `subscribe(cb)` follows
+ * the Svelte store contract (returns the unsubscribe function). `close()`
+ * detaches every listener added through this handle; the handle can be used
+ * again afterwards, which is what React's StrictMode needs.
+ */
+export interface LiveQuery<R = unknown> extends PromiseLike<R> {
+    readonly state: LiveState<R>;
+    /** Identity of the underlying instance (template key + params). */
+    readonly key: string;
+    subscribe(listener: LiveListener<R>): () => void;
+    /** Refetch now, keeping the current data until the response lands. */
+    refresh(): Promise<void>;
+    /**
+     * Local edit of the cached data, no request; overwritten by the next refetch
+     * and visible to every subscriber of the same query. An object merges into
+     * object data; an array or a function replaces.
+     */
+    patch(partial: Partial<R> | ((current: R) => R)): void;
+    /** Detach every listener added through this handle. */
+    close(): void;
+}
+export type Template = {
+    key: string;
+    kind: LiveQueryKind;
+    name?: string;
+    json: Record<string, unknown>;
+    /** Subject-stripped builder, used for dependency analysis only. */
+    builder: LiveBuilder;
+    shapeIri?: string;
+    reactive: boolean;
+    pinned: boolean;
+    deps?: QueryDependencies;
+    /** `deps` could not be computed (a query context in `where` is unset); recomputed on the next use. */
+    depsProvisional?: boolean;
+    instances: Map<string, Instance>;
+};
+export type Instance = {
+    key: string;
+    template: Template;
+    params: InstanceParams;
+    /** The bound builder this instance executes (what `.live()` was called on). */
+    builder: LiveBuilder;
+    state: LiveState;
+    /** Sequence of the latest issued request; a response carrying an older sequence is dropped. */
+    seq: number;
+    inflight: boolean;
+    /** Invalidated while a request was in flight: run one more request when it settles. */
+    staleWhileInflight: boolean;
+    /** Every node id the last result mentions, plus the subject(s). */
+    ids: Set<string>;
+    listeners: Set<LiveListener>;
+    /** Removed from its template (GC, routing change); a handle that still holds it re-resolves on use. */
+    dropped: boolean;
+    /** Set when a query context re-keyed this instance: handles follow it to the new one. */
+    movedTo?: Instance;
+    gcTimer?: ReturnType<typeof setTimeout>;
+};
+export type LiveQueryStoreOptions = {
+    /** Grace period before an instance with no listeners is dropped. */
+    gcMs: number;
+    /** Window in which a remote echo of a local change (or the reverse) folds into one refetch. */
+    echoMs: number;
+};
+/**
+ * Holds every live query in the runtime: templates (what is read) and
+ * instances (what it is applied to, and the data). Framework-free; UI layers
+ * subscribe to instances. One store per runtime, registered on `globalThis`
+ * (see `registry.ts`).
+ */
+export declare class LiveQueryStore {
+    readonly options: LiveQueryStoreOptions;
+    /** @internal */
+    readonly _templates: Map<string, Template>;
+    /** @internal Indexes read by the change matcher. */
+    readonly templatesByProp: Map<string, Set<Template>>;
+    /** @internal */
+    readonly templatesByShape: Map<string, Set<Template>>;
+    /** @internal */
+    readonly instancesById: Map<string, Set<Instance>>;
+    private readonly _disposers;
+    private readonly _feeds;
+    private readonly _recentChanges;
+    private _pendingRefetch;
+    private _flushScheduled;
+    constructor();
+    /** Register (or find) the template of `query`. Options merge into an existing template. */
+    template(query: LiveBuilder, opts?: LiveQueryOptions): Template;
+    private _template;
+    /** The registered templates (for database tuning, devtools). */
+    templates(): ReadonlyArray<{
+        key: string;
+        kind: LiveQueryKind;
+        name?: string;
+        json: Record<string, unknown>;
+    }>;
+    /** Compute the dependencies of every template now (they are otherwise computed on first use). */
+    prepare(): void;
+    /**
+     * The watch set of a template, computed once. When a query context used in
+     * `where` is not set yet, lowering throws; the template then gets provisional
+     * dependencies (its shape only) and is recomputed on its next use, which the
+     * context change triggers.
+     */
+    depsOf(template: Template): QueryDependencies;
+    private _index;
+    private _unindexTemplate;
+    /** @internal Get or create the instance of `template` for `params`, executing `builder`. */
+    instance(template: Template, params: InstanceParams, builder: LiveBuilder): Instance;
+    /**
+     * Subscribe to `query`. The first listener on an instance starts its fetch;
+     * identical queries share one instance and one request. A handle created
+     * without a listener holds nothing: its instance is released after the grace
+     * period unless something subscribes.
+     */
+    subscribe<R = unknown>(query: LiveBuilder, listener?: LiveListener<R>, opts?: LiveQueryOptions): LiveQuery<R>;
+    /** @internal The live instance for a possibly dropped one (same template, params and builder). */
+    _resolve(inst: Instance): Instance;
+    /** @internal */
+    _attach(inst: Instance, listener: LiveListener): void;
+    /** @internal */
+    _detach(inst: Instance, listener: LiveListener): void;
+    /** Refetch an instance, keeping its data on screen. Resolves when that request settles. */
+    refresh(inst: Instance): Promise<void>;
+    /**
+     * Local edit of an instance's data. Never touches the store. A patched
+     * instance counts as loaded (`success`), so `await live` resolves with it.
+     */
+    patch(inst: Instance, partial: unknown): void;
+    /**
+     * Refetch every instance matching `target`: a shape class or shape IRI
+     * (everything that scans or traverses it, as after a delete), a node
+     * reference (`{id}`), a query (its template), or a template. Never folded
+     * with other change events.
+     */
+    invalidate(target: ShapeConstructor<any> | string | {
+        id: string;
+    } | LiveBuilder | Template): void;
+    /** @internal Refetch a set of instances, folding in-flight ones into one follow-up request. */
+    _refetchAll(instances: Iterable<Instance>): void;
+    /**
+     * Tell the store that data changed. Every source ends here: local mutations
+     * (automatically, origin `local`), dataset change feeds (`feed`), application
+     * code via `publishChange()` (`app`) and `invalidate()` (`manual`).
+     *
+     * A local change and its remote confirmation carry identical effects; when
+     * they arrive within `options.echoMs` of each other they refetch once. Two
+     * events of the same origin are never folded — two writes to the same node
+     * in quick succession are two changes — and manual invalidations never are.
+     */
+    publish(event: ChangeEvent, origin?: ChangeOrigin): void;
+    private _scheduleFlush;
+    /**
+     * Local mutations. Select and ask events are ignored: the store's own fetches
+     * run through the same dispatch and must not feed back into it.
+     */
+    private _onDispatch;
+    /** Subscribe to the change feeds of the datasets currently routed; drop feeds of datasets that left. */
+    private _scanDatasets;
+    /**
+     * Storage changed (a dataset was set, pinned or unpinned): what is cached may
+     * come from a store that no longer answers, so instances nobody watches are
+     * dropped and watched ones fetch again. Also refreshes the feed subscriptions.
+     */
+    private _onRoutingChanged;
+    /** Drop every template and instance (tests). Subscriptions to sources stay. */
+    reset(): void;
+    /** @internal */
+    dispose(): void;
+    private _fetch;
+    private _applyResult;
+    private _collectIds;
+    private _setState;
+    /**
+     * A query context changed. An instance whose *subject* is that context is
+     * re-keyed to the new id (the builder resolves the context lazily, so it is
+     * reused); an instance that references it in `where` just fetches again.
+     */
+    private _onContextChange;
+    /** Remove an instance from its template (and the template when it is empty and not pinned). */
+    private _dropInstance;
+    private _scheduleGc;
+    private _cancelGc;
+}
+/** Every string value under an `id` key, at any depth. */
+export declare function collectIds(value: unknown, into: Set<string>): Set<string>;
+/** Deep equality over the plain-data results the store holds (objects, arrays, dates, primitives). */
+export declare function deepEqual(a: unknown, b: unknown): boolean;
+/** The runtime's live-query store (registered on `globalThis` when this module loads). */
+export declare function getLiveQueryStore(): LiveQueryStore;
+/** Publish a change from application code (your own transport, a server push). */
+export declare function publishChange(event: ChangeEvent): void;
+/** Refetch every live query that `target` can have affected. See {@link LiveQueryStore.invalidate}. */
+export declare function invalidate(target: ShapeConstructor<any> | string | {
+    id: string;
+} | LiveBuilder | Template): void;
+export type { ChangeEvent, ChangeOrigin, MutationEffects };
+/** Replace the store with a fresh one (tests). */
+export declare function resetLiveQueryStore(): LiveQueryStore;