@_linked/core 1.0.0 → 1.2.0-next.20260302120536

package/CHANGELOG.md

@@ -1,8 +1,80 @@
 # Changelog
 
+## 1.2.0
+
+### Minor Changes
+
+- [#9](https://github.com/Semantu/linked/pull/9) [`381067b`](https://github.com/Semantu/linked/commit/381067b0fbc25f4a0446c5f8cc0eec57ddded466) Thanks [@flyon](https://github.com/flyon)! - Replaced internal query representation with a canonical backend-agnostic IR AST. `SelectQuery`, `CreateQuery`, `UpdateQuery`, and `DeleteQuery` are now typed IR objects with `kind` discriminators, compact shape/property ID references, and expression trees — replacing the previous ad-hoc nested arrays. The public Shape DSL is unchanged; what changed is what `IQuadStore` implementations receive. Store result types (`ResultRow`, `SelectResult`, `CreateResult`, `UpdateResult`) are now exported. All factories expose `build()` as the primary method. See `documentation/intermediate-representation.md` for the full IR reference and migration guidance.
+
+- [#14](https://github.com/Semantu/linked/pull/14) [`b65e156`](https://github.com/Semantu/linked/commit/b65e15688ac173478e58e1dbb9f26dbaf5fc5a37) Thanks [@flyon](https://github.com/flyon)! - Add SPARQL conversion layer — compiles Linked IR queries into executable SPARQL and maps results back to typed DSL objects.
+
+  **New exports from `@_linked/core/sparql`:**
+
+  - **`SparqlStore`** — abstract base class for SPARQL-backed stores. Extend it and implement two methods to connect any SPARQL 1.1 endpoint:
+
+    ```ts
+    import { SparqlStore } from "@_linked/core/sparql";
+
+    class MyStore extends SparqlStore {
+      protected async executeSparqlSelect(
+        sparql: string
+      ): Promise<SparqlJsonResults> {
+        /* ... */
+      }
+      protected async executeSparqlUpdate(sparql: string): Promise<void> {
+        /* ... */
+      }
+    }
+    ```
+
+  - **IR → SPARQL string** convenience functions (full pipeline in one call):
+
+    - `selectToSparql(query, options?)` — SelectQuery → SPARQL string
+    - `createToSparql(query, options?)` — CreateQuery → SPARQL string
+    - `updateToSparql(query, options?)` — UpdateQuery → SPARQL string
+    - `deleteToSparql(query, options?)` — DeleteQuery → SPARQL string
+
+  - **IR → SPARQL algebra** (for stores that want to inspect/optimize the algebra before serialization):
+
+    - `selectToAlgebra(query, options?)` — returns `SparqlSelectPlan`
+    - `createToAlgebra(query, options?)` — returns `SparqlInsertDataPlan`
+    - `updateToAlgebra(query, options?)` — returns `SparqlDeleteInsertPlan`
+    - `deleteToAlgebra(query, options?)` — returns `SparqlDeleteInsertPlan`
+
+  - **Algebra → SPARQL string** serialization:
+
+    - `selectPlanToSparql(plan, options?)`, `insertDataPlanToSparql(plan, options?)`, `deleteInsertPlanToSparql(plan, options?)`, `deleteWherePlanToSparql(plan, options?)`
+    - `serializeAlgebraNode(node)`, `serializeExpression(expr)`, `serializeTerm(term)`
+
+  - **Result mapping** (SPARQL JSON results → typed DSL objects):
+
+    - `mapSparqlSelectResult(json, query)` — handles flat/nested/aggregated results with XSD type coercion
+    - `mapSparqlCreateResult(uri, query)` — echoes created fields with generated URI
+    - `mapSparqlUpdateResult(query)` — echoes updated fields
+
+  - **All algebra types** re-exported: `SparqlTerm`, `SparqlTriple`, `SparqlAlgebraNode`, `SparqlExpression`, `SparqlSelectPlan`, `SparqlInsertDataPlan`, `SparqlDeleteInsertPlan`, `SparqlDeleteWherePlan`, `SparqlPlan`, `SparqlOptions`, etc.
+
+  **Bug fixes included:**
+
+  - Fixed `isNodeReference()` in MutationQuery.ts — nested creates with predefined IDs (e.g., `{id: '...', name: 'Bestie'}`) now correctly insert entity data instead of only creating the link.
+
+  See [SPARQL Algebra Layer docs](./documentation/sparql-algebra.md) for the full type reference, conversion rules, and store implementation guide.
+
+## 1.1.0
+
+### Minor Changes
+
+- [#4](https://github.com/Semantu/linked/pull/4) [`c35e686`](https://github.com/Semantu/linked/commit/c35e6861600d7aa8683b4b288fc4d1dc74c4aff2) Thanks [@flyon](https://github.com/flyon)! - - Added `Shape.selectAll()` plus nested `selectAll()` support on sub-queries.
+  - Added inherited property deduplication via `NodeShape.getUniquePropertyShapes()` so subclass overrides win by label and are selected once.
+  - Improved `selectAll()` type inference (including nested queries) and excluded base `Shape` keys from inferred results.
+  - Added registration-time override guards: `minCount` cannot be lowered, `maxCount` cannot be increased, and `nodeKind` cannot be widened.
+  - Fixed `createPropertyShape` to preserve explicit `minCount: 0` / `maxCount: 0`.
+  - Expanded tests and README documentation for `selectAll`, CRUD return types, and multi-value update semantics.
+
 ## 1.0.0
 
 ### Major Changes
+
 This is a rebranding + extraction release. It moves the core query/shape system into `@_linked/core` and removes RDF models and React-specific code.
 
 Key changes:

package/README.md

@@ -1,11 +1,12 @@
 # @_linked/core
 Core Linked package for the query DSL, SHACL shape decorators/metadata, and package registration.
 
-Linked core gives you a type-safe, schema-parameterized query language and SHACL-driven Shape classes for linked data. It compiles queries into a plain JS query object that can be executed by a store.
+Linked core gives you a type-safe, schema-parameterized query language and SHACL-driven Shape classes for linked data. It compiles queries into a normalized [Intermediate Representation (IR)](./documentation/intermediate-representation.md) that can be executed by any store.
 
 ## Linked core offers
 
 - **Schema-Parameterized Query DSL**: TypeScript-embedded queries driven by your Shape definitions.
+- **Fully Inferred Result Types**: The TypeScript return type of every query is automatically inferred from the selected paths — no manual type annotations needed. Select `p.name` and get `{id: string; name: string}[]`. Select `p.friends.name` and get nested result types. This works for all operations: select, create, update, and delete.
 - **Shape Classes (SHACL)**: TypeScript classes that generate SHACL shape metadata.
 - **Object-Oriented Data Operations**: Query, create, update, and delete data using the same Shape-based API.
 - **Storage Routing**: `LinkedStorage` routes query objects to your configured store(s) that implement `IQuadStore`.
@@ -17,16 +18,151 @@ Linked core gives you a type-safe, schema-parameterized query language and SHACL
 npm install @_linked/core
 ```
 
-```typescript
-import {Shape, LinkedStorage} from '@_linked/core';
-import {linkedPackage} from '@_linked/core/utils/Package';
+## Repository setup (contributors)
+
+After cloning this repository, run:
+
+```bash
+npm install
+npm run setup
 ```
 
+`npm run setup` syncs `docs/agents` into local folders for agent tooling:
+
+- `.claude/agents`
+- `.agents/agents`
+
 ## Related packages
 
 - `@_linked/rdf-mem-store`: in-memory RDF store that implements `IQuadStore`.
 - `@_linked/react`: React bindings for Linked queries and shapes.
 
+## Documentation
+
+- [Intermediate Representation (IR)](./documentation/intermediate-representation.md)
+- [SPARQL Algebra Layer](./documentation/sparql-algebra.md)
+
+## How Linked works — from shapes to query results
+
+Linked turns TypeScript classes into a type-safe query pipeline. Here is the full flow, traced through a single example:
+
+```
+Shape class → DSL query → IR (AST) → Target query language → Execute → Map results
+```
+
+### 1. SHACL shapes from TypeScript classes
+
+Shape classes use decorators to generate SHACL metadata. These shapes define the data model, drive the DSL's type safety, and can be synced to a store for runtime data validation.
+
+```typescript
+@linkedShape
+export class Person extends Shape {
+  static targetClass = schema('Person');
+
+  @literalProperty({path: schema('name'), maxCount: 1})
+  get name(): string { return ''; }
+
+  @objectProperty({path: schema('knows'), shape: Person})
+  get friends(): ShapeSet<Person> { return null; }
+}
+```
+
+### 2. Type-safe query DSL with inferred result types
+
+The DSL uses these shape classes to provide compile-time checked queries. You cannot write a query that references a property not defined on the shape. The result type is **fully inferred** from the selected paths — no manual type annotations needed:
+
+```typescript
+// TypeScript infers: Promise<{id: string; name: string}[]>
+const result = await Person.select(p => p.name);
+
+// TypeScript infers: Promise<{id: string; friends: {id: string; name: string}[]}[]>
+const nested = await Person.select(p => p.friends.name);
+```
+
+### 3. SHACL-based Intermediate Representation (IR)
+
+The DSL compiles to a backend-agnostic AST — the [Intermediate Representation](./documentation/intermediate-representation.md). This is the contract between the DSL and any store implementation.
+
+```json
+{
+  "kind": "select",
+  "root": { "kind": "shape_scan", "shape": ".../Person", "alias": "a0" },
+  "projection": [
+    { "alias": "a1", "expression": { "kind": "property_expr", "sourceAlias": "a0", "property": ".../name" } }
+  ],
+  "resultMap": [{ "key": ".../name", "alias": "a1" }]
+}
+```
+
+The IR uses full SHACL-derived URIs for shapes and properties. Any store that implements `IQuadStore` receives these IR objects and translates them into its native query language.
+
+### 4. IR → SPARQL Algebra
+
+For SPARQL-backed stores, the IR is converted into a formal [SPARQL algebra](./documentation/sparql-algebra.md) — a tree of typed nodes aligned with the SPARQL 1.1 specification.
+
+```
+SparqlSelectPlan {
+  projection: [?a0, ?a0_name]
+  algebra: LeftJoin(
+    BGP(?a0 rdf:type <Person>),
+    BGP(?a0 <name> ?a0_name)       ← wrapped in OPTIONAL
+  )
+}
+```
+
+Properties are wrapped in `LeftJoin` (OPTIONAL) so missing values don't eliminate result rows.
+
+### 5. SPARQL Algebra → SPARQL string
+
+The algebra is a plain data structure — stores can inspect or optimize it before serialization (e.g., rewriting patterns, adding graph clauses, or pruning redundant joins).
+
+The algebra tree is then serialized into a SPARQL query string with automatic PREFIX generation:
+
+```sparql
+PREFIX rdf: <http://www.w3.org/1999/02/22-rdf-syntax-ns#>
+SELECT DISTINCT ?a0 ?a0_name
+WHERE {
+  ?a0 rdf:type <.../Person> .
+  OPTIONAL {
+    ?a0 <.../name> ?a0_name .
+  }
+}
+```
+
+### 6. Execute and map results
+
+The SPARQL endpoint returns JSON results, which are mapped back into typed result objects:
+
+```
+Endpoint returns:                        Mapped to:
+┌──────────┬──────────┐                  ┌──────────────────────────────┐
+│ a0       │ a0_name  │                  │ { id: ".../p1", name: "Semmy" } │
+│ .../p1   │ "Semmy"  │        →         │ { id: ".../p2", name: "Moa"   } │
+│ .../p2   │ "Moa"    │                  │ ...                          │
+└──────────┴──────────┘                  └──────────────────────────────┘
+```
+
+Values are automatically coerced: `xsd:boolean` → `boolean`, `xsd:integer` → `number`, `xsd:dateTime` → `Date`. Nested traversals are grouped and deduplicated into nested result objects.
+
+### The SparqlStore base class
+
+`SparqlStore` handles this entire pipeline. Concrete stores only implement the transport:
+
+```typescript
+import { SparqlStore } from '@_linked/core/sparql';
+
+class MyStore extends SparqlStore {
+  protected async executeSparqlSelect(sparql: string) {
+    // Send SPARQL to your endpoint, return JSON results
+  }
+  protected async executeSparqlUpdate(sparql: string) {
+    // Send SPARQL UPDATE to your endpoint
+  }
+}
+```
+
+See the [SPARQL Algebra Layer docs](./documentation/sparql-algebra.md) for the full type reference, conversion algorithm, and store implementation guide.
+
 ## Linked Package Setup
 
 Linked packages expose shapes, utilities, and ontologies through a small `package.ts` file. This makes module exports discoverable across Linked modules and enables linked decorators.
@@ -85,41 +221,35 @@ export class Person extends Shape {
 ## Queries: Create, Select, Update, Delete
 
 Queries are expressed with the same Shape classes and compile to a query object that a store executes.
+Use this section as a quick start. Detailed query variations are documented in `Query examples` below.
+
+A few quick examples:
 
+**1) Select one field for all matching nodes**
 ```typescript
-/* Result: Array<{id: string; name: string}> */
 const names = await Person.select((p) => p.name);
+/* names: {id: string; name: string}[] */
+```
 
-const myNode = {id: 'https://my.app/node1'};
-/* Result: {id: string; name: string} | null */
-const person = await Person.select(myNode, (p) => p.name);
-const missing = await Person.select({id: 'https://my.app/missing'}, (p) => p.name); // null
-
-/* Result: {id: string} & UpdatePartial<Person> */
-const created = await Person.create({
-  name: 'Alice',
-  knows: [{id: 'https://my.app/node2'}],
-});
+**2) Select all decorated fields of nested related nodes**
+```typescript
+const allFriends = await Person.select((p) => p.knows.selectAll());
+/* allFriends: {
+  id?: string; 
+  knows: {
+    id?: string; 
+    ...all decorated Person fields...
+  }[]
+	}[] */
+```
 
+**3) Apply a simple mutation**
+```typescript
+const myNode = {id: 'https://my.app/node1'};
 const updated = await Person.update(myNode, {
   name: 'Alicia',
 });
-
-// Overwrite a multi-value property
-const overwriteFriends = await Person.update(myNode, {
-  knows: [{id: 'https://my.app/node2'}],
-});
-
-// Add/remove items in a multi-value property
-const addRemoveFriends = await Person.update(myNode, {
-  knows: {
-    add: [{id: 'https://my.app/node3'}],
-    remove: [{id: 'https://my.app/node2'}],
-  },
-});
-
-/* Result: {deleted: Array<{id: string}>, count: number} */
-await Person.delete(myNode);
+/* updated: {id: string} & UpdatePartial<Person> */
 ```
 
 ## Storage configuration
@@ -172,10 +302,13 @@ Result types are inferred from your Shape definitions and the selected paths. Ex
 
 #### Basic selection
 ```typescript
-/* Result: Array<{id: string; name: string}> */
+/* names: {id: string; name: string}[] */
 const names = await Person.select((p) => p.name);
 
-/* Result: Array<{id: string; knows: Array<{id: string}>}> */
+/* friends: {
+  id: string; 
+  knows: { id: string }[]
+}[] */
 const friends = await Person.select((p) => p.knows);
 
 const dates = await Person.select((p) => [p.birthDate, p.name]);
@@ -202,6 +335,12 @@ const deep = await Person.select((p) => p.knows.bestFriend.name);
 const detailed = await Person.select((p) =>
   p.knows.select((f) => f.name),
 );
+
+const allPeople = await Person.selectAll();
+
+const detailedAll = await Person.select((p) =>
+  p.knows.selectAll(),
+);
 ```
 
 #### Where + equals
@@ -261,7 +400,9 @@ const custom = await Person.select((p) => ({
 }));
 ```
 
-#### Query As (type casting)
+#### Query As (type casting to a sub shape)
+If person.pets returns an array of Pets. And Dog extends Pet.
+And you want to select properties of those pets that are dogs:
 ```typescript
 const guards = await Person.select((p) => p.pets.as(Dog).guardDogLevel);
 ```
@@ -293,34 +434,171 @@ const preloaded = await Person.select((p) => [
 ]);
 ```
 
-#### Create / Update / Delete
+#### Create
+
 ```typescript
 /* Result: {id: string} & UpdatePartial<Person> */
 const created = await Person.create({name: 'Alice'});
+```
+Where UpdatePartial<Shape> reflects the created properties.
+
+#### Update
 
+Update will patch any property that you send as payload and leave the rest untouched.
+```typescript
+/* Result: {id: string} & UpdatePartial<Person> */
 const updated = await Person.update({id: 'https://my.app/node1'}, {name: 'Alicia'});
+```
+Returns:
+```json
+{
+  id:"https://my.app/node1",
+  name:"Alicia"
+}
+```
+
+**Updating multi-value properties**
+When updating a property that holds multiple values (one that returns an array in the results), you can either overwrite all the values with a new explicit array of values, or delete from/add to the current values.
 
-// Overwrite a multi-value property
-const overwriteFriends = await Person.update({id: 'https://my.app/node1'}, {
-  knows: [{id: 'https://my.app/node2'}],
+To overwrite all values:
+```typescript
+// Overwrite the full set of "knows" values.
+const overwriteFriends = await Person.update({id: 'https://my.app/person1'}, {
+  knows: [{id: 'https://my.app/person2'}],
 });
+```
+The result will contain an object with `updatedTo`, to indicate that previous values were overwritten to this new set of values:
+```json
+{
+  id: "https://my.app/person1",
+  knows: {
+    updatedTo: [{id:"https://my.app/person2"}],
+  }
+}
+``` 
 
-// Add/remove items in a multi-value property
-const addRemoveFriends = await Person.update({id: 'https://my.app/node1'}, {
+To make incremental changes to the current set of values you can provide an object with `add` and/or `remove` keys:
+```typescript
+// Add one value and remove one value without replacing the whole set.
+const addRemoveFriends = await Person.update({id: 'https://my.app/person1'}, {
   knows: {
-    add: [{id: 'https://my.app/node3'}],
-    remove: [{id: 'https://my.app/node2'}],
+    add: [{id: 'https://my.app/person2'}],
+    remove: [{id: 'https://my.app/person3'}],
   },
 });
+```
+This returns an object with the added and removed items
+```json
+{
+  id: "https://my.app/person1",
+  knows: {
+    added?: [{id:"https://my.app/person2"},
+    removed?: [{id:"https://my.app/person3"}],
+  }
+}
+```
+
 
-await Person.delete({id: 'https://my.app/node1'});
+#### Delete
+To delete a node entirely:
+
+```typescript
+/* Result: {deleted: Array<{id: string}>, count: number} */
+const deleted = await Person.delete({id: 'https://my.app/node1'});
+```
+Returns
+```json
+{
+  deleted:[
+    {id:"https://my.app/node1"}
+  ],
+  count:1
+}
 ```
 
+To delete multiple nodes pass an array:
+
+```typescript
+/* Result: {deleted: Array<{id: string}>, count: number} */
+const deleted = await Person.delete([{id: 'https://my.app/node1'},{id: 'https://my.app/node2'}]);
+```
+
+
+## Extending shapes
+
+Shape classes can extend other shape classes. Subclasses inherit property shapes from their superclasses and may override them.
+This example assumes `Person` from the `Shapes` section above.
+
+```typescript
+import {literalProperty} from '@_linked/core/shapes/SHACL';
+import {createNameSpace} from '@_linked/core/utils/NameSpace';
+import {linkedShape} from './package';
+
+const schema = createNameSpace('https://schema.org/');
+const EmployeeClass = schema('Employee');
+const name = schema('name');
+const employeeId = schema('employeeId');
+
+@linkedShape
+export class Employee extends Person {
+  static targetClass = EmployeeClass;
+
+  // Override inherited "name" with stricter constraints (still maxCount: 1)
+  @literalProperty({path: name, required: true, minLength: 2, maxCount: 1})
+  declare name: string;
+
+  @literalProperty({path: employeeId, required: true, maxCount: 1})
+  declare employeeId: string;
+}
+```
+
+Override behavior:
+
+- `NodeShape.getUniquePropertyShapes()` returns one property shape per label, with subclass overrides taking precedence.
+- Overrides must be tighten-only for `minCount`, `maxCount`, and `nodeKind` (widening is rejected at registration time).
+- If an override omits `minCount`, `maxCount`, or `nodeKind`, inherited values are kept.
+- Current scope: compatibility checks for `datatype`, `class`, and `pattern` are not enforced yet.
+
 ## TODO
 
 - Allow `preloadFor` to accept another query (not just a component).
 - Make and expose functions for auto syncing shapes to the graph.
 
+## Intermediate Representation (IR)
+
+Every Linked query compiles to a plain, JSON-serializable JavaScript object — the **Intermediate Representation**. This IR is the contract between the DSL and any storage backend. A store receives these objects and translates them into its native query language (SPARQL, SQL, etc.).
+
+For example, this DSL call:
+
+```typescript
+const names = await Person.select((p) => p.name);
+```
+
+produces the following IR object, which is passed to your store's `selectQuery()` method:
+
+```json
+{
+  "kind": "select",
+  "root": {"kind": "shape_scan", "shape": "https://schema.org/Person", "alias": "a0"},
+  "patterns": [],
+  "projection": [
+    {
+      "alias": "a1",
+      "expression": {"kind": "property_expr", "sourceAlias": "a0", "property": "https://schema.org/name"}
+    }
+  ],
+  "resultMap": [{"key": "name", "alias": "a1"}],
+  "singleResult": false
+}
+```
+
+All IR types are available from `@_linked/core/queries/IntermediateRepresentation`. See the full [Intermediate Representation docs](./documentation/intermediate-representation.md) for the complete type reference, examples, and a store implementer guide.
+
+**Store packages:**
+
+- `SparqlStore` base class — included in `@_linked/core/sparql`, extend it for any SPARQL endpoint
+- `@_linked/rdf-mem-store` — in-memory RDF store
+
 ## Changelog
 
 See [CHANGELOG.md](./CHANGELOG.md).

package/lib/cjs/index.js

@@ -61,6 +61,7 @@ const DeleteQuery = __importStar(require("./queries/DeleteQuery.js"));
 const CreateQuery = __importStar(require("./queries/CreateQuery.js"));
 const QueryParser = __importStar(require("./queries/QueryParser.js"));
 const QueryFactory = __importStar(require("./queries/QueryFactory.js"));
+const IntermediateRepresentation = __importStar(require("./queries/IntermediateRepresentation.js"));
 const NameSpace = __importStar(require("./utils/NameSpace.js"));
 const ShapeClass = __importStar(require("./utils/ShapeClass.js"));
 const cached = __importStar(require("./utils/cached.js"));
@@ -75,6 +76,7 @@ const shacl = __importStar(require("./ontologies/shacl.js"));
 const lincd = __importStar(require("./ontologies/lincd.js"));
 const owl = __importStar(require("./ontologies/owl.js"));
 const npm = __importStar(require("./ontologies/npm.js"));
+const Sparql = __importStar(require("./sparql/index.js"));
 const next_tick_1 = __importDefault(require("next-tick"));
 exports.nextTick = next_tick_1.default;
 function initModularApp() {
@@ -103,6 +105,7 @@ function initModularApp() {
         CreateQuery,
         QueryParser,
         QueryFactory,
+        IntermediateRepresentation,
         SHACLShapes,
         rdf,
         rdfs,
@@ -111,6 +114,7 @@ function initModularApp() {
         lincd,
         owl,
         npm,
+        Sparql,
     };
     var lincdExport = {};
     for (let fileKey in publicFiles) {

package/lib/cjs/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwCA,wCA+CC;AAvFD;;;;GAIG;AACH,4DAA8C;AAC9C,kFAAoE;AACpE,gFAAkE;AAClE,wEAA0D;AAC1D,kEAAoD;AACpD,kEAAoD;AACpD,yDAA2C;AAC3C,+DAAiD;AACjD,oEAAsD;AACtD,0DAA4C;AAC5C,oDAAsC;AACtC,sEAAwD;AACxD,sEAAwD;AACxD,0EAA4D;AAC5D,sEAAwD;AACxD,sEAAwD;AACxD,sEAAwD;AACxD,wEAA0D;AAC1D,gEAAkD;AAClD,kEAAoD;AACpD,0DAA4C;AAC5C,uDAAyC;AACzC,6EAA+D;AAC/D,uEAAyD;AACzD,uEAAyD;AACzD,yDAA2C;AAC3C,2DAA6C;AAC7C,yDAA2C;AAC3C,6DAA+C;AAC/C,6DAA+C;AAC/C,yDAA2C;AAC3C,yDAA2C;AAC3C,0DAAiC;AACzB,mBADD,mBAAQ,CACC;AAEhB,SAAgB,cAAc;IAC5B,IAAI,WAAW,GAAG;QAChB,OAAO;QACP,kBAAkB;QAClB,iBAAiB;QACjB,aAAa;QACb,OAAO;QACP,OAAO;QACP,KAAK;QACL,QAAQ;QACR,MAAM;QACN,SAAS;QACT,MAAM;QACN,GAAG;QACH,UAAU;QACV,IAAI;QACJ,aAAa;QACb,UAAU;QACV,UAAU;QACV,WAAW;QACX,WAAW;QACX,aAAa;QACb,WAAW;QACX,WAAW;QACX,WAAW;QACX,YAAY;QACZ,WAAW;QACX,GAAG;QACH,IAAI;QACJ,GAAG;QACH,KAAK;QACL,KAAK;QACL,GAAG;QACH,GAAG;KACJ,CAAC;IACF,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,KAAK,IAAI,OAAO,IAAI,WAAW,EAAE,CAAC;QAChC,IAAI,eAAe,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QAC3C,KAAK,IAAI,SAAS,IAAI,eAAe,EAAE,CAAC;YACtC,WAAW,CAAC,SAAS,CAAC,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC;IAC9C,CAAC;SAAM,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QACzC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AA0CA,wCAiDC;AA3FD;;;;GAIG;AACH,4DAA8C;AAC9C,kFAAoE;AACpE,gFAAkE;AAClE,wEAA0D;AAC1D,kEAAoD;AACpD,kEAAoD;AACpD,yDAA2C;AAC3C,+DAAiD;AACjD,oEAAsD;AACtD,0DAA4C;AAC5C,oDAAsC;AACtC,sEAAwD;AACxD,sEAAwD;AACxD,0EAA4D;AAC5D,sEAAwD;AACxD,sEAAwD;AACxD,sEAAwD;AACxD,wEAA0D;AAC1D,oGAAsF;AACtF,gEAAkD;AAClD,kEAAoD;AACpD,0DAA4C;AAC5C,uDAAyC;AACzC,6EAA+D;AAC/D,uEAAyD;AACzD,uEAAyD;AACzD,yDAA2C;AAC3C,2DAA6C;AAC7C,yDAA2C;AAC3C,6DAA+C;AAC/C,6DAA+C;AAC/C,yDAA2C;AAC3C,yDAA2C;AAC3C,0DAA4C;AAC5C,0DAAiC;AACzB,mBADD,mBAAQ,CACC;AAEhB,SAAgB,cAAc;IAC5B,IAAI,WAAW,GAAG;QAChB,OAAO;QACP,kBAAkB;QAClB,iBAAiB;QACjB,aAAa;QACb,OAAO;QACP,OAAO;QACP,KAAK;QACL,QAAQ;QACR,MAAM;QACN,SAAS;QACT,MAAM;QACN,GAAG;QACH,UAAU;QACV,IAAI;QACJ,aAAa;QACb,UAAU;QACV,UAAU;QACV,WAAW;QACX,WAAW;QACX,aAAa;QACb,WAAW;QACX,WAAW;QACX,WAAW;QACX,YAAY;QACZ,0BAA0B;QAC1B,WAAW;QACX,GAAG;QACH,IAAI;QACJ,GAAG;QACH,KAAK;QACL,KAAK;QACL,GAAG;QACH,GAAG;QACH,MAAM;KACP,CAAC;IACF,IAAI,WAAW,GAAG,EAAE,CAAC;IACrB,KAAK,IAAI,OAAO,IAAI,WAAW,EAAE,CAAC;QAChC,IAAI,eAAe,GAAG,WAAW,CAAC,OAAO,CAAC,CAAC;QAC3C,KAAK,IAAI,SAAS,IAAI,eAAe,EAAE,CAAC;YACtC,WAAW,CAAC,SAAS,CAAC,GAAG,eAAe,CAAC,SAAS,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IACD,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC;IAC9C,CAAC;SAAM,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QACzC,MAAM,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,WAAW,CAAC,CAAC;IAC9C,CAAC;AACH,CAAC"}

package/lib/cjs/interfaces/IQuadStore.d.ts

@@ -1,14 +1,26 @@
-import { CreateQuery } from '../queries/CreateQuery.js';
-import { DeleteQuery, DeleteResponse } from '../queries/DeleteQuery.js';
-import { SelectQuery } from '../queries/SelectQuery.js';
-import { UpdateQuery } from '../queries/UpdateQuery.js';
+import type { SelectQuery } from '../queries/SelectQuery.js';
+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';
+/**
+ * Store interface for executing IR queries.
+ *
+ * Implement this interface to back Linked with a custom storage engine
+ * (SPARQL endpoint, SQL database, in-memory store, etc.).
+ *
+ * Each method receives a canonical IR query object and returns the result.
+ * The calling layer (LinkedStorage / QueryParser) threads the precise
+ * DSL-level TypeScript result type back to the caller — the store only
+ * needs to produce data that matches the structural result types.
+ */
 export interface IQuadStore {
     /**
      * Prepares the store to be used.
      */
     init?(): Promise<any>;
-    selectQuery<ResultType>(query: SelectQuery<any>): Promise<ResultType>;
-    updateQuery?<RType>(q: UpdateQuery<RType>): Promise<RType>;
-    createQuery?<R>(q: CreateQuery<R>): Promise<R>;
+    selectQuery(query: SelectQuery): Promise<SelectResult>;
+    updateQuery?(query: UpdateQuery): Promise<UpdateResult>;
+    createQuery?(query: CreateQuery): Promise<CreateResult>;
     deleteQuery?(query: DeleteQuery): Promise<DeleteResponse>;
 }

package/lib/cjs/queries/CreateQuery.d.ts

@@ -1,18 +1,17 @@
 import { Shape } from '../shapes/Shape.js';
-import { NodeShape } from '../shapes/SHACL.js';
-import { LinkedQuery } from './SelectQuery.js';
 import { AddId, NodeDescriptionValue, UpdatePartial } from './QueryFactory.js';
 import { MutationQueryFactory } from './MutationQuery.js';
-export interface CreateQuery<ResponseType = null> extends LinkedQuery {
-    type: 'create';
-    shape: NodeShape;
-    description: NodeDescriptionValue;
-}
+import { IRCreateMutation } from './IntermediateRepresentation.js';
+/**
+ * The canonical CreateQuery type — an IR AST node representing a create mutation.
+ * This is the type received by IQuadStore.createQuery().
+ */
+export type CreateQuery = IRCreateMutation;
 export type CreateResponse<U> = AddId<U, true>;
 export declare class CreateQueryFactory<ShapeType extends Shape, U extends UpdatePartial<ShapeType>> extends MutationQueryFactory {
     shapeClass: typeof Shape;
     readonly id: string;
     readonly description: NodeDescriptionValue;
     constructor(shapeClass: typeof Shape, updateObjectOrFn: U);
-    getQueryObject(): CreateQuery<AddId<U, true>>;
+    build(): CreateQuery;
 }

package/lib/cjs/queries/CreateQuery.js

@@ -2,18 +2,18 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CreateQueryFactory = void 0;
 const MutationQuery_js_1 = require("./MutationQuery.js");
+const IRMutation_js_1 = require("./IRMutation.js");
 class CreateQueryFactory extends MutationQuery_js_1.MutationQueryFactory {
     constructor(shapeClass, updateObjectOrFn) {
         super();
         this.shapeClass = shapeClass;
         this.description = this.convertUpdateObject(updateObjectOrFn, this.shapeClass.shape, true);
     }
-    getQueryObject() {
-        return {
-            type: 'create',
+    build() {
+        return (0, IRMutation_js_1.buildCanonicalCreateMutationIR)({
             shape: this.shapeClass.shape,
             description: this.description,
-        };
+        });
     }
 }
 exports.CreateQueryFactory = CreateQueryFactory;

package/lib/cjs/queries/CreateQuery.js.map

@@ -1 +1 @@
-{"version":3,"file":"CreateQuery.js","sourceRoot":"","sources":["../../../src/queries/CreateQuery.ts"],"names":[],"mappings":";;;AAIA,yDAAwD;AAUxD,MAAa,kBAGX,SAAQ,uCAAoB;IAI5B,YACS,UAAwB,EAC/B,gBAAmB;QAEnB,KAAK,EAAE,CAAC;QAHD,eAAU,GAAV,UAAU,CAAc;QAI/B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,mBAAmB,CACzC,gBAAgB,EAChB,IAAI,CAAC,UAAU,CAAC,KAAK,EACrB,IAAI,CACL,CAAC;IACJ,CAAC;IAED,cAAc;QACZ,OAAO;YACL,IAAI,EAAE,QAAQ;YACd,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK;YAC5B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC;IACJ,CAAC;CACF;AA1BD,gDA0BC"}
+{"version":3,"file":"CreateQuery.js","sourceRoot":"","sources":["../../../src/queries/CreateQuery.ts"],"names":[],"mappings":";;;AAEA,yDAAwD;AAExD,mDAA+D;AAU/D,MAAa,kBAGX,SAAQ,uCAAoB;IAI5B,YACS,UAAwB,EAC/B,gBAAmB;QAEnB,KAAK,EAAE,CAAC;QAHD,eAAU,GAAV,UAAU,CAAc;QAI/B,IAAI,CAAC,WAAW,GAAG,IAAI,CAAC,mBAAmB,CACzC,gBAAgB,EAChB,IAAI,CAAC,UAAU,CAAC,KAAK,EACrB,IAAI,CACL,CAAC;IACJ,CAAC;IAED,KAAK;QACH,OAAO,IAAA,8CAA8B,EAAC;YACpC,KAAK,EAAE,IAAI,CAAC,UAAU,CAAC,KAAK;YAC5B,WAAW,EAAE,IAAI,CAAC,WAAW;SAC9B,CAAC,CAAC;IACL,CAAC;CACF;AAzBD,gDAyBC"}