@coasys/ad4m 0.13.0-test-5 → 0.13.0-test-6

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (63) hide show
  1. package/lib/index.cjs +610 -337
  2. package/lib/index.js +608 -338
  3. package/lib/src/Ad4mClient.d.ts +1 -1
  4. package/lib/src/Ad4mClient.js +2 -1
  5. package/lib/src/agent/AgentClient.d.ts +16 -0
  6. package/lib/src/agent/AgentClient.js +74 -4
  7. package/lib/src/cache/PersistentCache.d.ts +40 -0
  8. package/lib/src/cache/PersistentCache.js +139 -0
  9. package/lib/src/expression/ExpressionClient.d.ts +8 -0
  10. package/lib/src/expression/ExpressionClient.js +113 -5
  11. package/lib/src/index.d.ts +1 -0
  12. package/lib/src/index.js +1 -0
  13. package/lib/src/model/Ad4mModel.js +29 -57
  14. package/lib/src/model/Ad4mModel.test.js +688 -1434
  15. package/lib/src/model/ModelQueryBuilder.js +0 -9
  16. package/lib/src/model/Subject.js +6 -6
  17. package/lib/src/model/query-surreal.d.ts +44 -0
  18. package/lib/src/model/query-surreal.js +249 -0
  19. package/lib/src/model/relation-filtering.test.js +15 -15
  20. package/lib/src/model/surreal-utils.d.ts +42 -0
  21. package/lib/src/model/surreal-utils.js +128 -0
  22. package/lib/src/model/types.d.ts +0 -1
  23. package/lib/src/perspectives/PerspectiveClient.d.ts +0 -1
  24. package/lib/src/perspectives/PerspectiveClient.js +5 -13
  25. package/lib/src/perspectives/PerspectiveProxy.js +0 -3
  26. package/lib/src/perspectives/PerspectiveResolver.d.ts +1 -0
  27. package/lib/src/perspectives/PerspectiveResolver.js +11 -0
  28. package/lib/src/runtime/RuntimeResolver.d.ts +1 -28
  29. package/lib/src/runtime/RuntimeResolver.js +4 -197
  30. package/lib/src/schema.gql +1 -27
  31. package/lib/src/shacl/SHACLShape.test.js +0 -82
  32. package/package.json +1 -1
  33. package/src/Ad4mClient.test.ts +14 -4
  34. package/src/Ad4mClient.ts +2 -1
  35. package/src/agent/AgentClient.ts +84 -2
  36. package/src/cache/PersistentCache.ts +145 -0
  37. package/src/cache/cache.test.ts +713 -0
  38. package/src/expression/ExpressionClient.ts +137 -3
  39. package/src/index.ts +1 -0
  40. package/src/model/Ad4mModel.test.ts +1 -61
  41. package/src/model/Ad4mModel.ts +31 -57
  42. package/src/model/ModelQueryBuilder.ts +0 -6
  43. package/src/model/types.ts +1 -1
  44. package/src/perspectives/PerspectiveClient.ts +7 -17
  45. package/src/perspectives/PerspectiveProxy.ts +0 -3
  46. package/lib/src/model/hydration-batch.d.ts +0 -34
  47. package/lib/src/model/hydration-batch.js +0 -147
  48. package/lib/src/model/hydration-batching.test.d.ts +0 -7
  49. package/lib/src/model/hydration-batching.test.js +0 -456
  50. package/lib/src/model/model-manifest.d.ts +0 -41
  51. package/lib/src/model/model-manifest.js +0 -11
  52. package/lib/src/model/query-cache.test.d.ts +0 -1
  53. package/lib/src/model/query-cache.test.js +0 -43
  54. package/lib/src/model/query-sparql-batch.d.ts +0 -17
  55. package/lib/src/model/query-sparql-batch.js +0 -260
  56. package/lib/src/model/query-sparql.test.d.ts +0 -1
  57. package/lib/src/model/query-sparql.test.js +0 -312
  58. package/lib/src/model/subscription-delta.test.d.ts +0 -24
  59. package/lib/src/model/subscription-delta.test.js +0 -180
  60. package/lib/src/model/subscription-pool.d.ts +0 -39
  61. package/lib/src/model/subscription-pool.js +0 -165
  62. package/lib/src/perspectives/PerspectiveClient.test.d.ts +0 -1
  63. package/lib/src/perspectives/PerspectiveClient.test.js +0 -224
@@ -1,43 +0,0 @@
1
- import { getCachedResult, setCachedResult, invalidatePerspectiveCache, clearQueryCache, queryCacheSize } from './query-cache';
2
- describe('query-cache', () => {
3
- beforeEach(() => {
4
- clearQueryCache();
5
- });
6
- describe('lazy eviction', () => {
7
- it('should remove expired entries when setting a new one', () => {
8
- // Insert with a very short TTL
9
- setCachedResult('p1', 'SELECT ?x', 'result1', 1);
10
- expect(queryCacheSize()).toBe(1);
11
- // Wait for expiry
12
- const start = Date.now();
13
- while (Date.now() - start < 5) { /* busy wait 5ms */ }
14
- // Expired entry should still be in the map (not yet evicted)
15
- // but getCachedResult should return undefined
16
- expect(getCachedResult('p1', 'SELECT ?x')).toBeUndefined();
17
- // Setting a new entry should evict the expired one
18
- setCachedResult('p2', 'SELECT ?y', 'result2', 10000);
19
- // Only the new entry should remain
20
- expect(queryCacheSize()).toBe(1);
21
- expect(getCachedResult('p2', 'SELECT ?y')).toBe('result2');
22
- });
23
- });
24
- describe('invalidatePerspectiveCache', () => {
25
- it('should remove all entries for a specific perspective', () => {
26
- setCachedResult('p1', 'query1', 'r1', 10000);
27
- setCachedResult('p1', 'query2', 'r2', 10000);
28
- setCachedResult('p2', 'query1', 'r3', 10000);
29
- expect(queryCacheSize()).toBe(3);
30
- invalidatePerspectiveCache('p1');
31
- expect(queryCacheSize()).toBe(1);
32
- expect(getCachedResult('p1', 'query1')).toBeUndefined();
33
- expect(getCachedResult('p1', 'query2')).toBeUndefined();
34
- expect(getCachedResult('p2', 'query1')).toBe('r3');
35
- });
36
- it('should not affect other perspectives', () => {
37
- setCachedResult('p1', 'q', 'r1', 10000);
38
- setCachedResult('p2', 'q', 'r2', 10000);
39
- invalidatePerspectiveCache('p3');
40
- expect(queryCacheSize()).toBe(2);
41
- });
42
- });
43
- });
@@ -1,17 +0,0 @@
1
- /**
2
- * Batch SPARQL query builder for Ad4mModel eager-loading (includes).
3
- *
4
- * Uses direct triple + named graph storage model.
5
- * Each AD4M link is stored as: <source> <predicate> <target> in a named graph
6
- * with metadata in the default graph keyed by graph IRI.
7
- *
8
- * @module
9
- */
10
- import type { Query, ModelMetadata } from "./types";
11
- /**
12
- * Build a single SPARQL query that fetches root instances plus all
13
- * included relations in one query using UNION branches.
14
- *
15
- * Uses direct triple patterns in named graphs with metadata in default graph.
16
- */
17
- export declare function buildBatchSPARQLQuery(rootMetadata: ModelMetadata, query: Query, rootModelClass: any): string;
@@ -1,260 +0,0 @@
1
- /**
2
- * Batch SPARQL query builder for Ad4mModel eager-loading (includes).
3
- *
4
- * Uses direct triple + named graph storage model.
5
- * Each AD4M link is stored as: <source> <predicate> <target> in a named graph
6
- * with metadata in the default graph keyed by graph IRI.
7
- *
8
- * @module
9
- */
10
- import { resolveParentPredicate } from "./query-common";
11
- import { getRelationsMetadata } from "./decorators";
12
- import { Literal } from "../Literal";
13
- // ──────────────────────────────────────────────────────────
14
- // Helpers
15
- // ──────────────────────────────────────────────────────────
16
- function iri(value) {
17
- return `<${value}>`;
18
- }
19
- /**
20
- * Check if a string value looks like a URI (has a scheme).
21
- */
22
- function looksLikeUri(value) {
23
- return /^[a-zA-Z][a-zA-Z0-9+\-._]*:/.test(value);
24
- }
25
- /**
26
- * Convert a JS value to its literal: IRI form.
27
- */
28
- function valueToLiteralIri(value) {
29
- if (typeof value === 'string') {
30
- if (looksLikeUri(value))
31
- return value;
32
- return Literal.from(value).toUrl();
33
- }
34
- if (typeof value === 'number')
35
- return Literal.from(value).toUrl();
36
- if (typeof value === 'boolean')
37
- return Literal.from(value).toUrl();
38
- return Literal.from(String(value)).toUrl();
39
- }
40
- /**
41
- * Determine if a property stores values as literal: IRIs.
42
- */
43
- function isLiteralStoredProperty(propMeta) {
44
- if (propMeta.flag)
45
- return false;
46
- if (propMeta.resolveLanguage && propMeta.resolveLanguage !== "literal")
47
- return false;
48
- return true;
49
- }
50
- function buildConformanceJoins(metadata, sourceVar, prefix) {
51
- const joins = [];
52
- const filters = [];
53
- let hasConformance = false;
54
- for (const [, propMeta] of Object.entries(metadata.properties)) {
55
- if (propMeta.required) {
56
- if (propMeta.getter)
57
- continue;
58
- hasConformance = true;
59
- if (propMeta.flag && propMeta.initial) {
60
- joins.push(`
61
- ${sourceVar} ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
62
- }
63
- else {
64
- joins.push(`
65
- ${sourceVar} ${iri(propMeta.predicate)} ?${prefix}_cfTarget_${propMeta.name} .`);
66
- }
67
- }
68
- }
69
- if (!hasConformance) {
70
- for (const [, propMeta] of Object.entries(metadata.properties)) {
71
- if (propMeta.initial) {
72
- if (propMeta.flag) {
73
- joins.push(`
74
- ${sourceVar} ${iri(propMeta.predicate)} ${iri(propMeta.initial)} .`);
75
- }
76
- else {
77
- joins.push(`
78
- ${sourceVar} ${iri(propMeta.predicate)} ?${prefix}_cfInitAny_${propMeta.name} .`);
79
- }
80
- break;
81
- }
82
- }
83
- }
84
- return { joins, filters };
85
- }
86
- function flattenIncludeTree(parentDepth, parentClass, includeMap, nextDepth) {
87
- const branches = [];
88
- const relMeta = getRelationsMetadata(parentClass);
89
- for (const [relName, includeValue] of Object.entries(includeMap)) {
90
- const meta = relMeta[relName];
91
- if (!meta || !meta.target)
92
- continue;
93
- const TargetClass = meta.target();
94
- const targetMetadata = TargetClass.getModelMetadata
95
- ? TargetClass.getModelMetadata()
96
- : { className: "Unknown", properties: {}, relations: {} };
97
- const depth = nextDepth.value++;
98
- const direction = meta.kind === 'belongsToOne' || meta.kind === 'belongsToMany'
99
- ? 'reverse' : 'forward';
100
- const nestedInclude = typeof includeValue === 'object' && includeValue !== null
101
- ? includeValue.include
102
- : undefined;
103
- branches.push({
104
- depth,
105
- relationName: relName,
106
- parentDepth,
107
- parentPredicate: meta.predicate,
108
- targetClass: TargetClass,
109
- targetMetadata,
110
- includeMap: nestedInclude,
111
- direction,
112
- });
113
- if (nestedInclude) {
114
- branches.push(...flattenIncludeTree(depth, TargetClass, nestedInclude, nextDepth));
115
- }
116
- }
117
- return branches;
118
- }
119
- // ──────────────────────────────────────────────────────────
120
- // Main entry point
121
- // ──────────────────────────────────────────────────────────
122
- /**
123
- * Build a single SPARQL query that fetches root instances plus all
124
- * included relations in one query using UNION branches.
125
- *
126
- * Uses direct triple patterns in named graphs with metadata in default graph.
127
- */
128
- export function buildBatchSPARQLQuery(rootMetadata, query, rootModelClass) {
129
- const includeMap = query.include;
130
- if (!includeMap || Object.keys(includeMap).length === 0) {
131
- throw new Error("buildBatchSPARQLQuery requires query.include to be non-empty");
132
- }
133
- const nextDepth = { value: 1 };
134
- const branches = flattenIncludeTree(0, rootModelClass, includeMap, nextDepth);
135
- // Root conformance
136
- const rootConformance = buildConformanceJoins(rootMetadata, "?source", "root");
137
- const rootJoins = [...rootConformance.joins];
138
- const rootFilters = [...rootConformance.filters];
139
- if (query.parent) {
140
- const parentPredicate = resolveParentPredicate(query.parent, rootModelClass);
141
- rootJoins.push(`
142
- ${iri(query.parent.id)} ${iri(parentPredicate)} ?source .`);
143
- }
144
- if (query.where) {
145
- for (const [propertyName, condition] of Object.entries(query.where)) {
146
- if (propertyName === "base" || propertyName === "id") {
147
- if (Array.isArray(condition)) {
148
- const formatted = condition.map(v => iri(v)).join(", ");
149
- rootFilters.push(`?source IN (${formatted})`);
150
- }
151
- else if (typeof condition === "string") {
152
- rootFilters.push(`?source = ${iri(condition)}`);
153
- }
154
- continue;
155
- }
156
- if (propertyName === "author" || propertyName === "timestamp")
157
- continue;
158
- const propMeta = rootMetadata.properties[propertyName];
159
- if (!propMeta)
160
- continue;
161
- const useParseLiteral = isLiteralStoredProperty(propMeta);
162
- if (typeof condition === "string" || typeof condition === "number" || typeof condition === "boolean") {
163
- if (useParseLiteral) {
164
- // For literal-stored properties, just add a join for conformance — filtering is done in JS
165
- rootJoins.push(`
166
- ?source ${iri(propMeta.predicate)} ?root_wTarget_eq_${propertyName} .`);
167
- }
168
- else {
169
- rootJoins.push(`
170
- ?source ${iri(propMeta.predicate)} ${iri(String(condition))} .`);
171
- }
172
- }
173
- else if (Array.isArray(condition)) {
174
- if (useParseLiteral) {
175
- // For literal-stored properties, just add a join for conformance — filtering is done in JS
176
- rootJoins.push(`
177
- ?source ${iri(propMeta.predicate)} ?root_wTarget_${propertyName} .`);
178
- }
179
- else {
180
- const formatted = condition.map(v => iri(v)).join(", ");
181
- rootJoins.push(`
182
- ?source ${iri(propMeta.predicate)} ?root_wTarget_${propertyName} .`);
183
- rootFilters.push(`?root_wTarget_${propertyName} IN (${formatted})`);
184
- }
185
- }
186
- }
187
- }
188
- const rootJoinClause = rootJoins.join("\n");
189
- const rootFilterClause = rootFilters.length > 0
190
- ? `FILTER(\n ${rootFilters.join(" &&\n ")}\n )`
191
- : "";
192
- const unionBranches = [];
193
- // Depth 0: root — direct triple pattern with named graph
194
- unionBranches.push(`
195
- {
196
- ${rootJoinClause}
197
- GRAPH ?linkGraph { ?source ?predicate ?target . }
198
- FILTER(isIRI(?source) && isIRI(?predicate))
199
- ?linkGraph <ad4m://ontology/author> ?author .
200
- ?linkGraph <ad4m://ontology/timestamp> ?timestamp .
201
- ${rootFilterClause}
202
- BIND("0" AS ?depth)
203
- BIND("" AS ?parentBase)
204
- BIND("" AS ?relationName)
205
- }
206
- `);
207
- // Depth N: include branches
208
- for (const branch of branches) {
209
- const childConformance = buildConformanceJoins(branch.targetMetadata, "?source", `d${branch.depth}`);
210
- const childJoinClause = childConformance.joins.join("\n");
211
- const childFilterClause = childConformance.filters.length > 0
212
- ? `FILTER(\n ${childConformance.filters.join(" &&\n ")}\n )`
213
- : "";
214
- const parentJoinClause = branch.parentDepth === 0 ? rootJoinClause.replace(/\?source/g, '?parentBase') : '';
215
- const parentFilterClause = branch.parentDepth === 0 ? rootFilterClause.replace(/\?source/g, '?parentBase') : '';
216
- if (branch.direction === 'forward') {
217
- // Forward: parent --predicate--> child (source)
218
- unionBranches.push(`
219
- {
220
- # Depth ${branch.depth}: ${branch.relationName} (forward)
221
- ?parentBase ${iri(branch.parentPredicate)} ?source .
222
- ${childJoinClause}
223
- GRAPH ?linkGraph { ?source ?predicate ?target . }
224
- FILTER(isIRI(?source) && isIRI(?predicate))
225
- ?linkGraph <ad4m://ontology/author> ?author .
226
- ?linkGraph <ad4m://ontology/timestamp> ?timestamp .
227
- ${childFilterClause}
228
- ${parentJoinClause}
229
- ${parentFilterClause}
230
- BIND("${branch.depth}" AS ?depth)
231
- BIND("${branch.relationName}" AS ?relationName)
232
- }
233
- `);
234
- }
235
- else {
236
- // Reverse: child (source) --predicate--> parent
237
- unionBranches.push(`
238
- {
239
- # Depth ${branch.depth}: ${branch.relationName} (reverse)
240
- ?source ${iri(branch.parentPredicate)} ?parentBase .
241
- ${childJoinClause}
242
- GRAPH ?linkGraph { ?source ?predicate ?target . }
243
- FILTER(isIRI(?source) && isIRI(?predicate))
244
- ?linkGraph <ad4m://ontology/author> ?author .
245
- ?linkGraph <ad4m://ontology/timestamp> ?timestamp .
246
- ${childFilterClause}
247
- ${parentJoinClause}
248
- ${parentFilterClause}
249
- BIND("${branch.depth}" AS ?depth)
250
- BIND("${branch.relationName}" AS ?relationName)
251
- }
252
- `);
253
- }
254
- }
255
- return `
256
- SELECT ?depth ?parentBase ?relationName ?source ?predicate ?target ?author ?timestamp WHERE {
257
- ${unionBranches.join("\n UNION\n")}
258
- }
259
- `.trim();
260
- }
@@ -1 +0,0 @@
1
- export {};
@@ -1,312 +0,0 @@
1
- import { buildSPARQLOrderLimitOffset, buildSPARQLQuery, hasJsOnlyWhereFilters } from './query-sparql';
2
- // Minimal stubs for ModelMetadata — buildSPARQLOrderLimitOffset only uses the query arg
3
- const emptyMetadata = { properties: {}, relations: {} };
4
- // Metadata with a required (non-literal) property and a literal-stored property
5
- const richMetadata = {
6
- properties: {
7
- name: {
8
- name: 'name',
9
- predicate: 'flux://name',
10
- required: true,
11
- resolveLanguage: 'literal',
12
- },
13
- category: {
14
- name: 'category',
15
- predicate: 'flux://category',
16
- required: true,
17
- resolveLanguage: 'did:lang:abc', // non-literal → URI stored
18
- },
19
- description: {
20
- name: 'description',
21
- predicate: 'flux://description',
22
- initial: 'literal://string:empty',
23
- resolveLanguage: 'literal',
24
- },
25
- },
26
- relations: {},
27
- };
28
- const emptyRelations = {};
29
- describe('hasJsOnlyWhereFilters', () => {
30
- it('returns false when no where clause', () => {
31
- expect(hasJsOnlyWhereFilters(richMetadata, emptyRelations, undefined)).toBe(false);
32
- });
33
- it('returns false when where has literal-stored property with equality filter (pushed to SPARQL)', () => {
34
- expect(hasJsOnlyWhereFilters(richMetadata, emptyRelations, { name: 'Pasta' })).toBe(false);
35
- });
36
- it('returns true when where has literal-stored property with comparison operator', () => {
37
- // gt/lt/gte/lte/between/contains remain JS-only
38
- const meta = { properties: { rating: { name: 'rating', predicate: 'flux://rating', required: true, resolveLanguage: 'literal' } }, relations: {} };
39
- expect(hasJsOnlyWhereFilters(meta, emptyRelations, { rating: { gt: 5 } })).toBe(true);
40
- });
41
- it('returns false when where only has non-literal property filter', () => {
42
- expect(hasJsOnlyWhereFilters(richMetadata, emptyRelations, { category: 'some://uri' })).toBe(false);
43
- });
44
- it('returns true when where has author filter', () => {
45
- expect(hasJsOnlyWhereFilters(richMetadata, emptyRelations, { author: 'did:key:abc' })).toBe(true);
46
- });
47
- it('returns true when where has timestamp filter', () => {
48
- expect(hasJsOnlyWhereFilters(richMetadata, emptyRelations, { timestamp: { gt: 100 } })).toBe(true);
49
- });
50
- it('returns true for belongsToOne reverse relation', () => {
51
- const relMeta = { parent: { kind: 'belongsToOne', predicate: 'flux://parent' } };
52
- const meta = { properties: { parent: { name: 'parent', predicate: 'flux://parent' } }, relations: {} };
53
- expect(hasJsOnlyWhereFilters(meta, relMeta, { parent: 'some://id' })).toBe(true);
54
- });
55
- });
56
- describe('buildSPARQLQuery — SPARQL-level pagination via subquery', () => {
57
- const modelClass = {};
58
- it('includes LIMIT/OFFSET in a pagination subquery when query has them and no JS-only filters', () => {
59
- const query = { limit: 10, offset: 0, where: { category: 'some://uri' } };
60
- const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
61
- // SPARQL should contain LIMIT inside the pagination subquery
62
- expect(sparql).toContain('LIMIT 10');
63
- // The outer query should still exist
64
- expect(sparql).toContain('SELECT ?source ?predicate ?target');
65
- // Should have a subquery pattern
66
- expect(sparql).toContain('SELECT DISTINCT ?source');
67
- });
68
- it('does NOT include LIMIT/OFFSET when JS-only where filters exist', () => {
69
- // author is a JS-only filter
70
- const query = { limit: 10, offset: 0, where: { author: 'did:key:abc' } };
71
- const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
72
- expect(sparql).not.toContain('LIMIT');
73
- expect(sparql).not.toContain('OFFSET');
74
- });
75
- });
76
- describe('buildSPARQLOrderLimitOffset', () => {
77
- it('always returns empty string (pagination uses subquery pattern instead)', () => {
78
- expect(buildSPARQLOrderLimitOffset(emptyMetadata, {})).toBe('');
79
- expect(buildSPARQLOrderLimitOffset(emptyMetadata, { limit: 50 })).toBe('');
80
- expect(buildSPARQLOrderLimitOffset(emptyMetadata, { limit: 50, offset: 100 })).toBe('');
81
- expect(buildSPARQLOrderLimitOffset(emptyMetadata, { order: { timestamp: 'DESC' } })).toBe('');
82
- expect(buildSPARQLOrderLimitOffset(emptyMetadata, {
83
- order: { timestamp: 'DESC' },
84
- limit: 50,
85
- offset: 100,
86
- })).toBe('');
87
- });
88
- });
89
- describe('buildSPARQLQuery — parse_literal push-down filters', () => {
90
- const modelClass = {};
91
- it('generates parse_literal FILTER for equality on literal property', () => {
92
- const query = { where: { name: 'Alice' } };
93
- const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
94
- expect(sparql).toContain('<ad4m://fn/parse_literal>');
95
- expect(sparql).toContain('STR(<ad4m://fn/parse_literal>(?wTarget_name)) = "Alice"');
96
- });
97
- it('generates parse_literal IN FILTER for array on literal property', () => {
98
- const query = { where: { name: ['Alice', 'Bob'] } };
99
- const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
100
- expect(sparql).toContain('STR(<ad4m://fn/parse_literal>(?wTarget_name)) IN ("Alice", "Bob")');
101
- });
102
- it('generates parse_literal NOT FILTER for not condition', () => {
103
- const query = { where: { name: { not: 'deleted' } } };
104
- const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
105
- expect(sparql).toContain('STR(<ad4m://fn/parse_literal>(?wTarget_name)) != "deleted"');
106
- });
107
- it('does NOT use parse_literal for comparison operators (gt/lt)', () => {
108
- const meta = {
109
- properties: {
110
- rating: { name: 'rating', predicate: 'flux://rating', required: true, resolveLanguage: 'literal' },
111
- },
112
- relations: {},
113
- };
114
- const query = { where: { rating: { gt: 5 } } };
115
- const sparql = buildSPARQLQuery(meta, emptyRelations, query, modelClass);
116
- expect(sparql).not.toContain('parse_literal');
117
- expect(sparql).toContain('?wTarget_cmp_rating');
118
- });
119
- it('does NOT use parse_literal for non-literal properties', () => {
120
- const query = { where: { category: 'some://uri' } };
121
- const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
122
- expect(sparql).not.toContain('parse_literal');
123
- expect(sparql).toContain('<some://uri>');
124
- });
125
- });
126
- describe('buildSPARQLQuery — structural correctness', () => {
127
- const modelClass = {};
128
- it('generates valid SPARQL with parent filter', () => {
129
- const query = {
130
- limit: 50,
131
- offset: 0,
132
- parent: { id: 'flux://channel-123', predicate: 'flux://has_message' },
133
- where: { category: 'some://uri' },
134
- };
135
- const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
136
- expect(sparql).toContain('<flux://channel-123>');
137
- // SPARQL-level pagination via subquery
138
- expect(sparql).toContain('LIMIT 50');
139
- expect(sparql).toContain('SELECT DISTINCT ?source');
140
- });
141
- it('does not allow injection through where clause IRI values', () => {
142
- const query = {
143
- where: { category: 'some://uri"> . } UNION { SELECT * WHERE { ?s ?p ?o' },
144
- };
145
- const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
146
- // Value should be wrapped in angle brackets as an IRI
147
- expect(sparql).toContain('<some://uri');
148
- });
149
- });
150
- describe('buildSPARQLQuery — NOT with array push-down', () => {
151
- const modelClass = {};
152
- it('generates NOT IN filter for NOT with array of values', () => {
153
- const query = { where: { name: { not: ['deleted', 'archived'] } } };
154
- const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
155
- // Should use NOT IN with parse_literal for literal properties
156
- expect(sparql).toContain('NOT IN');
157
- expect(sparql).toContain('"deleted"');
158
- expect(sparql).toContain('"archived"');
159
- });
160
- });
161
- describe('buildSPARQLQuery — mixed push-down + JS-only', () => {
162
- const modelClass = {};
163
- const mixedMeta = {
164
- properties: {
165
- name: { name: 'name', predicate: 'flux://name', required: true, resolveLanguage: 'literal' },
166
- rating: { name: 'rating', predicate: 'flux://rating', required: true, resolveLanguage: 'literal' },
167
- },
168
- relations: {},
169
- };
170
- it('pushes equality to SPARQL but keeps gt as JS-only', () => {
171
- const query = { where: { name: 'Alice', rating: { gt: 5 } } };
172
- const sparql = buildSPARQLQuery(mixedMeta, emptyRelations, query, modelClass);
173
- // name equality should be pushed to SPARQL
174
- expect(sparql).toContain('parse_literal');
175
- expect(sparql).toContain('Alice');
176
- // hasJsOnlyWhereFilters should return true because of rating.gt
177
- expect(hasJsOnlyWhereFilters(mixedMeta, emptyRelations, query.where)).toBe(true);
178
- });
179
- });
180
- describe('buildSPARQLQuery — non-literal and flag properties', () => {
181
- const modelClass = {};
182
- it('does NOT use parse_literal for non-literal (resolveLanguage) properties', () => {
183
- const meta = {
184
- properties: {
185
- avatar: { name: 'avatar', predicate: 'flux://avatar', required: true, resolveLanguage: 'did:lang:some-language' },
186
- },
187
- relations: {},
188
- };
189
- const query = { where: { avatar: 'https://example.com/pic.jpg' } };
190
- const sparql = buildSPARQLQuery(meta, emptyRelations, query, modelClass);
191
- expect(sparql).not.toContain('parse_literal');
192
- });
193
- it('does NOT use parse_literal for flag properties', () => {
194
- const meta = {
195
- properties: {
196
- isPublic: { name: 'isPublic', predicate: 'flux://isPublic', flag: true, initial: 'flux://true' },
197
- },
198
- relations: {},
199
- };
200
- const query = { where: { isPublic: 'flux://true' } };
201
- const sparql = buildSPARQLQuery(meta, emptyRelations, query, modelClass);
202
- expect(sparql).not.toContain('parse_literal');
203
- });
204
- });
205
- describe('buildSPARQLQuery — IRI correctness', () => {
206
- const modelClass = {};
207
- it('uses <ad4m://fn/parse_literal> IRI, not fn::parse_literal SurrealDB syntax', () => {
208
- const query = { where: { name: 'test' } };
209
- const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
210
- expect(sparql).toContain('<ad4m://fn/parse_literal>');
211
- expect(sparql).not.toContain('fn::parse_literal');
212
- });
213
- });
214
- // ──────────────────────────────────────────────────────────
215
- // SPARQL-level pagination (LIMIT/OFFSET in generated queries)
216
- // ──────────────────────────────────────────────────────────
217
- describe('SPARQL-level pagination', () => {
218
- const modelClass = {};
219
- it('includes LIMIT in SPARQL when query specifies limit', () => {
220
- const query = { limit: 30 };
221
- const sparql = buildSPARQLQuery(emptyMetadata, emptyRelations, query, modelClass);
222
- expect(sparql).toContain('LIMIT 30');
223
- expect(sparql).toContain('SELECT DISTINCT ?source');
224
- });
225
- it('includes OFFSET in SPARQL when query specifies offset > 0', () => {
226
- const query = { limit: 20, offset: 40 };
227
- const sparql = buildSPARQLQuery(emptyMetadata, emptyRelations, query, modelClass);
228
- expect(sparql).toContain('LIMIT 20');
229
- expect(sparql).toContain('OFFSET 40');
230
- });
231
- it('does NOT include OFFSET when offset is 0', () => {
232
- const query = { limit: 10, offset: 0 };
233
- const sparql = buildSPARQLQuery(emptyMetadata, emptyRelations, query, modelClass);
234
- expect(sparql).toContain('LIMIT 10');
235
- expect(sparql).not.toContain('OFFSET');
236
- });
237
- it('includes ORDER BY in subquery when query.order is specified', () => {
238
- const query = { limit: 10, order: { name: 'DESC' } };
239
- const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
240
- expect(sparql).toContain('ORDER BY DESC(');
241
- expect(sparql).toContain('LIMIT 10');
242
- });
243
- it('does NOT default to ORDER BY timestamp when paginating without explicit order', () => {
244
- const query = { limit: 30 };
245
- const sparql = buildSPARQLQuery(emptyMetadata, emptyRelations, query, modelClass);
246
- expect(sparql).not.toContain('ORDER BY');
247
- expect(sparql).not.toContain('pg_minTs');
248
- });
249
- it('does NOT push pagination to SPARQL when JS-only where filters exist (author)', () => {
250
- const query = { limit: 10, where: { author: 'did:key:abc' } };
251
- const sparql = buildSPARQLQuery(emptyMetadata, emptyRelations, query, modelClass);
252
- expect(sparql).not.toContain('LIMIT');
253
- expect(sparql).not.toContain('OFFSET');
254
- });
255
- it('does NOT push pagination to SPARQL when JS-only where filters exist (gt operator)', () => {
256
- const meta = {
257
- properties: {
258
- rating: { name: 'rating', predicate: 'flux://rating', required: true, resolveLanguage: 'literal' },
259
- },
260
- relations: {},
261
- };
262
- const query = { limit: 10, where: { rating: { gt: 5 } } };
263
- const sparql = buildSPARQLQuery(meta, emptyRelations, query, modelClass);
264
- expect(sparql).not.toContain('LIMIT');
265
- });
266
- it('wraps pagination in a subquery (outer SELECT fetches all links for the page)', () => {
267
- const query = { limit: 5, offset: 10 };
268
- const sparql = buildSPARQLQuery(emptyMetadata, emptyRelations, query, modelClass);
269
- expect(sparql).toContain('SELECT ?source ?predicate ?target ?author ?timestamp');
270
- expect(sparql).toContain('SELECT DISTINCT ?source');
271
- expect(sparql).toContain('LIMIT 5');
272
- expect(sparql).toContain('OFFSET 10');
273
- });
274
- });
275
- describe('buildSPARQLQuery — set-difference patterns', () => {
276
- const modelClass = {};
277
- // Subgroups are grandchildren of channels (channel → conversation → subgroup).
278
- // Never assume direct child relationships in set-difference queries.
279
- // A global EXISTS pattern (no parent scoping) should match items regardless of depth.
280
- it('generates global EXISTS without parent scoping when no parent filter', () => {
281
- const meta = {
282
- properties: {
283
- status: { name: 'status', predicate: 'flux://status', required: true, resolveLanguage: 'literal' },
284
- },
285
- relations: {},
286
- };
287
- const query = { where: { status: 'active' } };
288
- const sparql = buildSPARQLQuery(meta, emptyRelations, query, modelClass);
289
- // Without a parent filter, the query should not scope to any specific parent
290
- // This ensures grandchildren (items at any depth) are matched
291
- expect(sparql).not.toContain('flux://has_child');
292
- expect(sparql).toContain('SELECT ?source ?predicate ?target');
293
- });
294
- });
295
- describe('buildSPARQLQuery — RDF 1.2 reifier patterns', () => {
296
- const modelClass = {};
297
- it('uses rdf:reifies instead of GRAPH for link metadata', () => {
298
- const query = { limit: 10 };
299
- const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
300
- expect(sparql).toContain('<http://www.w3.org/1999/02/22-rdf-syntax-ns#reifies>');
301
- expect(sparql).toContain('<http://www.w3.org/1999/02/22-rdf-syntax-ns#reifies> <<(');
302
- expect(sparql).toContain('?_reifier');
303
- expect(sparql).not.toContain('GRAPH');
304
- expect(sparql).not.toContain('?linkGraph');
305
- });
306
- it('binds author and timestamp on the reifier node', () => {
307
- const query = {};
308
- const sparql = buildSPARQLQuery(richMetadata, emptyRelations, query, modelClass);
309
- expect(sparql).toContain('?_reifier <ad4m://ontology/author> ?author');
310
- expect(sparql).toContain('?_reifier <ad4m://ontology/timestamp> ?timestamp');
311
- });
312
- });
@@ -1,24 +0,0 @@
1
- /**
2
- * Tests for the delta fast-path logic used in subscription-pool.ts.
3
- *
4
- * The delta optimisation in pooledSubscribe's onResult handler:
5
- * 1. Checks if new rows are a strict superset of previous rows
6
- * 2. Extracts added rows (new triples not in prev set)
7
- * 3. Verifies ALL added rows have source URIs not already in previous results
8
- * 4. If condition 3 fails (existing source got new links), falls back to full rehydration
9
- *
10
- * These tests validate the detection logic in isolation.
11
- */
12
- type Row = {
13
- source: string;
14
- predicate: string;
15
- target: string;
16
- };
17
- /**
18
- * Replicates the delta-path eligibility check from subscription-pool.ts
19
- */
20
- declare function detectDeltaPath(prevArr: Row[], newArr: Row[]): {
21
- useDelta: boolean;
22
- addedRows: Row[];
23
- reason?: string;
24
- };