@coasys/ad4m 0.10.1-release-candidate-5 → 0.11.0

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.
@@ -1,8 +1,47 @@
1
1
  import { Literal } from "../Literal";
2
2
  import { Link } from "../links/Links";
3
3
  import { PerspectiveProxy } from "../perspectives/PerspectiveProxy";
4
- import { makeRandomPrologAtom } from "./decorators";
5
- import { singularToPlural } from "./util";
4
+ import { makeRandomPrologAtom, PropertyOptions, CollectionOptions, ModelOptions } from "./decorators";
5
+ import { singularToPlural, pluralToSingular, propertyNameToSetterName, collectionToAdderName, collectionToRemoverName, collectionToSetterName } from "./util";
6
+
7
+ // JSON Schema type definitions
8
+ interface JSONSchemaProperty {
9
+ type: string | string[];
10
+ items?: JSONSchemaProperty;
11
+ properties?: { [key: string]: JSONSchemaProperty };
12
+ required?: string[];
13
+ "x-ad4m"?: {
14
+ through?: string;
15
+ resolveLanguage?: string;
16
+ local?: boolean;
17
+ writable?: boolean;
18
+ initial?: string;
19
+ };
20
+ }
21
+
22
+ interface JSONSchema {
23
+ $schema?: string;
24
+ title?: string;
25
+ $id?: string;
26
+ type?: string;
27
+ properties?: { [key: string]: JSONSchemaProperty };
28
+ required?: string[];
29
+ "x-ad4m"?: {
30
+ namespace?: string;
31
+ className?: string;
32
+ };
33
+ }
34
+
35
+ interface JSONSchemaToModelOptions {
36
+ name: string;
37
+ namespace?: string;
38
+ predicateTemplate?: string;
39
+ predicateGenerator?: (title: string, property: string) => string;
40
+ propertyMapping?: Record<string, string>;
41
+ resolveLanguage?: string;
42
+ local?: boolean;
43
+ propertyOptions?: Record<string, Partial<PropertyOptions>>;
44
+ }
6
45
 
7
46
  type ValueTuple = [name: string, value: any, resolve?: boolean];
8
47
  type WhereOps = {
@@ -12,6 +51,7 @@ type WhereOps = {
12
51
  lte: number; // less than or equal to
13
52
  gt: number; // greater than
14
53
  gte: number; // greater than or equal to
54
+ contains: string | number; // substring/element check
15
55
  };
16
56
  type WhereCondition = string | number | boolean | string[] | number[] | { [K in keyof WhereOps]?: WhereOps[K] };
17
57
  type Where = { [propertyName: string]: WhereCondition };
@@ -32,6 +72,60 @@ export type AllInstancesResult = { AllInstances: Ad4mModel[]; TotalCount?: numbe
32
72
  export type ResultsWithTotalCount<T> = { results: T[]; totalCount?: number };
33
73
  export type PaginationResult<T> = { results: T[]; totalCount?: number; pageSize: number; pageNumber: number };
34
74
 
75
+ /**
76
+ * Metadata for a single property extracted from decorators.
77
+ */
78
+ export interface PropertyMetadata {
79
+ /** The property name */
80
+ name: string;
81
+ /** The predicate URI (through value) */
82
+ predicate: string;
83
+ /** Whether the property is required */
84
+ required: boolean;
85
+ /** Whether the property is writable */
86
+ writable: boolean;
87
+ /** Initial value if specified */
88
+ initial?: string;
89
+ /** Language for resolution (e.g., "literal") */
90
+ resolveLanguage?: string;
91
+ /** Custom Prolog getter code */
92
+ getter?: string;
93
+ /** Custom Prolog setter code */
94
+ setter?: string;
95
+ /** Whether stored locally only */
96
+ local?: boolean;
97
+ /** Transform function */
98
+ transform?: (value: any) => any;
99
+ /** Whether this is a flag property */
100
+ flag?: boolean;
101
+ }
102
+
103
+ /**
104
+ * Metadata for a single collection extracted from decorators.
105
+ */
106
+ export interface CollectionMetadata {
107
+ /** The collection name */
108
+ name: string;
109
+ /** The predicate URI (through value) */
110
+ predicate: string;
111
+ /** Filter conditions */
112
+ where?: { isInstance?: any; condition?: string };
113
+ /** Whether stored locally only */
114
+ local?: boolean;
115
+ }
116
+
117
+ /**
118
+ * Complete model metadata extracted from decorators.
119
+ */
120
+ export interface ModelMetadata {
121
+ /** The model class name from @ModelOptions */
122
+ className: string;
123
+ /** Map of property name to metadata */
124
+ properties: Record<string, PropertyMetadata>;
125
+ /** Map of collection name to metadata */
126
+ collections: Record<string, CollectionMetadata>;
127
+ }
128
+
35
129
  function capitalize(word: string): string {
36
130
  return word.charAt(0).toUpperCase() + word.slice(1);
37
131
  }
@@ -171,6 +265,44 @@ function buildLimitQuery(limit?: number): string {
171
265
  return `takeN(InstancesWithOffset, ${limit}, AllInstances)`;
172
266
  }
173
267
 
268
+ function normalizeNamespaceString(namespace: string): string {
269
+ if (!namespace) return '';
270
+ if (namespace.includes('://')) {
271
+ const [scheme, rest] = namespace.split('://');
272
+ const path = (rest || '').replace(/\/+$/,'');
273
+ return `${scheme}://${path}`;
274
+ } else {
275
+ return namespace.replace(/\/+$/,'');
276
+ }
277
+ }
278
+
279
+ function normalizeSchemaType(type?: string | string[]): string | undefined {
280
+ if (!type) return undefined;
281
+ if (typeof type === "string") return type;
282
+ if (Array.isArray(type) && type.length > 0) {
283
+ const nonNull = type.find((t) => t !== "null");
284
+ return nonNull || type[0];
285
+ }
286
+ return undefined;
287
+ }
288
+
289
+ function isSchemaType(schema: JSONSchemaProperty, expectedType: string): boolean {
290
+ return normalizeSchemaType(schema.type) === expectedType;
291
+ }
292
+
293
+ function isArrayType(schema: JSONSchemaProperty): boolean {
294
+ return isSchemaType(schema, "array");
295
+ }
296
+
297
+ function isObjectType(schema: JSONSchemaProperty): boolean {
298
+ return isSchemaType(schema, "object");
299
+ }
300
+
301
+ function isNumericType(schema: JSONSchemaProperty): boolean {
302
+ const normalized = normalizeSchemaType(schema.type);
303
+ return normalized === "number" || normalized === "integer";
304
+ }
305
+
174
306
  /**
175
307
  * Base class for defining data models in AD4M.
176
308
  *
@@ -305,6 +437,143 @@ export class Ad4mModel {
305
437
  return classCache[perspectiveID];
306
438
  }
307
439
 
440
+ /**
441
+ * Extracts metadata from decorators for query building.
442
+ *
443
+ * @description
444
+ * This method reads the metadata stored by decorators (@Property, @Collection, etc.)
445
+ * and returns it in a structured format that's easier to work with for query builders
446
+ * and other systems that need to introspect model structure.
447
+ *
448
+ * The metadata includes:
449
+ * - Class name from @ModelOptions
450
+ * - Property metadata (predicates, types, constraints, etc.)
451
+ * - Collection metadata (predicates, filters, etc.)
452
+ *
453
+ * For models created via `fromJSONSchema()`, this method will derive metadata from
454
+ * the stored `__properties` and `__collections` structures that were populated during
455
+ * the dynamic class creation. If these structures are empty but a JSON schema was
456
+ * attached to the class, it can fall back to deriving metadata from that schema.
457
+ *
458
+ * @returns Structured metadata object containing className, properties, and collections
459
+ * @throws Error if the class doesn't have @ModelOptions decorator
460
+ *
461
+ * @example
462
+ * ```typescript
463
+ * @ModelOptions({ name: "Recipe" })
464
+ * class Recipe extends Ad4mModel {
465
+ * @Property({ through: "recipe://name", resolveLanguage: "literal" })
466
+ * name: string = "";
467
+ *
468
+ * @Collection({ through: "recipe://ingredient" })
469
+ * ingredients: string[] = [];
470
+ * }
471
+ *
472
+ * const metadata = Recipe.getModelMetadata();
473
+ * console.log(metadata.className); // "Recipe"
474
+ * console.log(metadata.properties.name.predicate); // "recipe://name"
475
+ * console.log(metadata.collections.ingredients.predicate); // "recipe://ingredient"
476
+ * ```
477
+ */
478
+ public static getModelMetadata(): ModelMetadata {
479
+ // Access the prototype with any type to access decorator-added properties
480
+ const prototype = this.prototype as any;
481
+
482
+ // Validate that the class has @ModelOptions decorator
483
+ // The decorator sets prototype.className, so we check for its existence
484
+ if (!prototype.className || prototype.className === 'Ad4mModel') {
485
+ throw new Error("Model class must be decorated with @ModelOptions");
486
+ }
487
+
488
+ // Extract className
489
+ const className = prototype.className;
490
+
491
+ // Extract properties from prototype.__properties
492
+ const propertiesMetadata: Record<string, PropertyMetadata> = {};
493
+ const prototypeProperties = prototype.__properties || {};
494
+
495
+ for (const [propertyName, opts] of Object.entries(prototypeProperties)) {
496
+ const options = opts as PropertyOptions & { required?: boolean; flag?: boolean };
497
+ propertiesMetadata[propertyName] = {
498
+ name: propertyName,
499
+ predicate: options.through || "",
500
+ required: options.required || false,
501
+ writable: options.writable || false,
502
+ ...(options.initial !== undefined && { initial: options.initial }),
503
+ ...(options.resolveLanguage !== undefined && { resolveLanguage: options.resolveLanguage }),
504
+ ...(options.getter !== undefined && { getter: options.getter }),
505
+ ...(options.setter !== undefined && { setter: options.setter }),
506
+ ...(options.local !== undefined && { local: options.local }),
507
+ ...(options.transform !== undefined && { transform: options.transform }),
508
+ ...(options.flag !== undefined && { flag: options.flag })
509
+ };
510
+ }
511
+
512
+ // Extract collections from prototype.__collections
513
+ const collectionsMetadata: Record<string, CollectionMetadata> = {};
514
+ const prototypeCollections = prototype.__collections || {};
515
+
516
+ for (const [collectionName, opts] of Object.entries(prototypeCollections)) {
517
+ const options = opts as CollectionOptions;
518
+ collectionsMetadata[collectionName] = {
519
+ name: collectionName,
520
+ predicate: options.through || "",
521
+ ...(options.where !== undefined && { where: options.where }),
522
+ ...(options.local !== undefined && { local: options.local })
523
+ };
524
+ }
525
+
526
+ // Fallback: If both structures are empty but a JSON schema is attached, derive from it
527
+ // This handles edge cases where fromJSONSchema() was called but metadata wasn't properly populated
528
+ const hasProperties = Object.keys(propertiesMetadata).length > 0;
529
+ const hasCollections = Object.keys(collectionsMetadata).length > 0;
530
+ const hasMetadata = hasProperties || hasCollections;
531
+
532
+ if (!hasMetadata && prototype.__jsonSchema) {
533
+ // Derive metadata from the attached JSON schema
534
+ const schema = prototype.__jsonSchema;
535
+ const options = prototype.__jsonSchemaOptions || {};
536
+
537
+ if (schema.properties) {
538
+ for (const [propertyName, propertySchema] of Object.entries(schema.properties)) {
539
+ const isArray = isArrayType(propertySchema as JSONSchemaProperty);
540
+ const predicate = this.determinePredicate(
541
+ schema,
542
+ propertyName,
543
+ propertySchema as JSONSchemaProperty,
544
+ this.determineNamespace(schema, options),
545
+ options
546
+ );
547
+
548
+ if (isArray) {
549
+ collectionsMetadata[propertyName] = {
550
+ name: propertyName,
551
+ predicate: predicate,
552
+ ...(propertySchema["x-ad4m"]?.local !== undefined && { local: propertySchema["x-ad4m"].local })
553
+ };
554
+ } else {
555
+ const isRequired = schema.required?.includes(propertyName) || false;
556
+ propertiesMetadata[propertyName] = {
557
+ name: propertyName,
558
+ predicate: predicate,
559
+ required: isRequired,
560
+ writable: propertySchema["x-ad4m"]?.writable !== false,
561
+ ...(propertySchema["x-ad4m"]?.resolveLanguage && { resolveLanguage: propertySchema["x-ad4m"].resolveLanguage }),
562
+ ...(propertySchema["x-ad4m"]?.initial && { initial: propertySchema["x-ad4m"].initial }),
563
+ ...(propertySchema["x-ad4m"]?.local !== undefined && { local: propertySchema["x-ad4m"].local })
564
+ };
565
+ }
566
+ }
567
+ }
568
+ }
569
+
570
+ return {
571
+ className,
572
+ properties: propertiesMetadata,
573
+ collections: collectionsMetadata
574
+ };
575
+ }
576
+
308
577
  /**
309
578
  * Constructs a new model instance.
310
579
  *
@@ -443,6 +712,506 @@ export class Ad4mModel {
443
712
  return fullQuery;
444
713
  }
445
714
 
715
+ /**
716
+ * Generates a SurrealQL query from a Query object.
717
+ *
718
+ * @description
719
+ * This method translates high-level query parameters into a SurrealQL query string
720
+ * that can be executed against the SurrealDB backend. Unlike Prolog queries which
721
+ * operate on SDNA-aware predicates, SurrealQL queries operate directly on raw links
722
+ * stored in SurrealDB.
723
+ *
724
+ * The generated query uses a CTE (Common Table Expression) pattern:
725
+ * 1. First, identify candidate base expressions by filtering links based on where conditions
726
+ * 2. Then, for each candidate base, resolve properties and collections via subqueries
727
+ * 3. Finally, apply ordering, pagination (LIMIT/START) at the SQL level
728
+ *
729
+ * Key architectural notes:
730
+ * - SurrealDB stores only raw links (source, predicate, target, author, timestamp)
731
+ * - No SDNA knowledge at the database level
732
+ * - Properties are resolved via subqueries that look for links with specific predicates
733
+ * - Collections are similar but return multiple values instead of one
734
+ * - Special fields (base, author, timestamp) are accessed directly, not via subqueries
735
+ *
736
+ * @param perspective - The perspective to query (used for metadata extraction)
737
+ * @param query - Query parameters (where, order, limit, offset, properties, collections)
738
+ * @returns Complete SurrealQL query string ready for execution
739
+ *
740
+ * @example
741
+ * ```typescript
742
+ * const query = Recipe.queryToSurrealQL(perspective, {
743
+ * where: { name: "Pasta", rating: { gt: 4 } },
744
+ * order: { timestamp: "DESC" },
745
+ * limit: 10
746
+ * });
747
+ * // Returns: SELECT source AS base, array::first(target[WHERE predicate = ...]) AS name, ...
748
+ * // FROM link WHERE ... GROUP BY source ORDER BY timestamp DESC LIMIT 10
749
+ * ```
750
+ */
751
+ public static async queryToSurrealQL(perspective: PerspectiveProxy, query: Query): Promise<string> {
752
+ const metadata = this.getModelMetadata();
753
+ const { source, where, order, offset, limit } = query;
754
+
755
+ // Build list of graph traversal filters for required predicates
756
+ const graphTraversalFilters: string[] = [];
757
+
758
+ // Add source filter if specified (filter to nodes that are children of this source)
759
+ // Source filter means: find targets of 'ad4m://has_child' links from the specified source
760
+ if (source) {
761
+ // Use graph traversal: node must be target of has_child link from source
762
+ graphTraversalFilters.push(
763
+ `count(<-link[WHERE perspective = $perspective AND in.uri = ${this.formatSurrealValue(source)} AND predicate = 'ad4m://has_child']) > 0`
764
+ );
765
+ }
766
+
767
+ // Add filters for required properties
768
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
769
+ if (propMeta.required) {
770
+ // For flag properties, also filter by the target value
771
+ if (propMeta.flag && propMeta.initial) {
772
+ graphTraversalFilters.push(
773
+ `count(->link[WHERE perspective = $perspective AND predicate = '${propMeta.predicate}' AND out.uri = '${propMeta.initial}']) > 0`
774
+ );
775
+ } else {
776
+ graphTraversalFilters.push(
777
+ `count(->link[WHERE perspective = $perspective AND predicate = '${propMeta.predicate}']) > 0`
778
+ );
779
+ }
780
+ }
781
+ }
782
+
783
+ // If no required properties, we need at least one property to define the model
784
+ // Use any property with an initial value as the defining characteristic
785
+ if (graphTraversalFilters.length === 0) {
786
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
787
+ if (propMeta.initial) {
788
+ // For flag properties, also filter by the target value
789
+ if (propMeta.flag) {
790
+ graphTraversalFilters.push(
791
+ `count(->link[WHERE perspective = $perspective AND predicate = '${propMeta.predicate}' AND out.uri = '${propMeta.initial}']) > 0`
792
+ );
793
+ } else {
794
+ graphTraversalFilters.push(
795
+ `count(->link[WHERE perspective = $perspective AND predicate = '${propMeta.predicate}']) > 0`
796
+ );
797
+ }
798
+ break; // Just need one defining property
799
+ }
800
+ }
801
+ }
802
+
803
+ // Build user WHERE clause filters using graph traversal
804
+ const userWhereClause = this.buildGraphTraversalWhereClause(metadata, where);
805
+
806
+ // Build complete WHERE clause using graph traversal filters
807
+ const whereConditions: string[] = [];
808
+
809
+ // Add all graph traversal filters for required properties
810
+ whereConditions.push(...graphTraversalFilters);
811
+
812
+ // Add user where conditions if any
813
+ if (userWhereClause) {
814
+ whereConditions.push(userWhereClause);
815
+ }
816
+
817
+ // Always ensure node has at least one link in this perspective
818
+ whereConditions.push(`count(->link[WHERE perspective = $perspective]) > 0`);
819
+
820
+ // Build the query FROM node using direct graph traversal in WHERE
821
+ // This avoids slow subqueries and uses graph indexes for fast traversal
822
+ const fullQuery = `
823
+ SELECT
824
+ id AS source,
825
+ uri AS source_uri,
826
+ ->link[WHERE perspective = $perspective] AS links
827
+ FROM node
828
+ WHERE ${whereConditions.join(' AND ')}
829
+ `.trim();
830
+
831
+ return fullQuery;
832
+ }
833
+
834
+ /**
835
+ * Builds the WHERE clause for SurrealQL queries using graph traversal syntax.
836
+ *
837
+ * @description
838
+ * Translates where conditions into graph traversal filters: `->link[WHERE ...]`
839
+ * This is more efficient than nested SELECTs because SurrealDB can optimize graph traversals.
840
+ *
841
+ * Handles several condition types:
842
+ * - Simple equality: `{ name: "Pasta" }` → `->link[WHERE predicate = 'X' AND out.uri = 'Pasta']`
843
+ * - Arrays (IN clause): `{ name: ["Pasta", "Pizza"] }` → `->link[WHERE predicate = 'X' AND out.uri IN [...]]`
844
+ * - NOT operators: Use `NOT` prefix
845
+ * - Comparison operators (gt, gte, lt, lte, etc.): Handled in post-query JavaScript filtering
846
+ * - Special fields: base uses `uri` directly, author/timestamp handled post-query
847
+ *
848
+ * @param metadata - Model metadata containing property predicates
849
+ * @param where - Where conditions from the query
850
+ * @returns Graph traversal WHERE clause filters, or empty string if no conditions
851
+ *
852
+ * @private
853
+ */
854
+ private static buildGraphTraversalWhereClause(metadata: ModelMetadata, where?: Where): string {
855
+ if (!where) return '';
856
+
857
+ const conditions: string[] = [];
858
+
859
+ for (const [propertyName, condition] of Object.entries(where)) {
860
+ // Check if this is a special field (base, author, timestamp)
861
+ // Note: author and timestamp filtering is done in JavaScript after query
862
+ const isSpecial = ['base', 'author', 'timestamp'].includes(propertyName);
863
+
864
+ if (isSpecial) {
865
+ // Skip author and timestamp - they'll be filtered in JavaScript
866
+ // Only handle 'base' (which maps to 'uri') here
867
+ if (propertyName === 'author' || propertyName === 'timestamp') {
868
+ continue; // Skip - will be filtered post-query
869
+ }
870
+
871
+ const columnName = 'uri'; // base maps to uri in node table
872
+
873
+ // Handle base/uri field directly
874
+ if (Array.isArray(condition)) {
875
+ // Array values (IN clause)
876
+ const formattedValues = condition.map(v => this.formatSurrealValue(v)).join(', ');
877
+ conditions.push(`${columnName} IN [${formattedValues}]`);
878
+ } else if (typeof condition === 'object' && condition !== null) {
879
+ // Operator object
880
+ const ops = condition as any;
881
+ if (ops.not !== undefined) {
882
+ if (Array.isArray(ops.not)) {
883
+ const formattedValues = ops.not.map(v => this.formatSurrealValue(v)).join(', ');
884
+ conditions.push(`${columnName} NOT IN [${formattedValues}]`);
885
+ } else {
886
+ conditions.push(`${columnName} != ${this.formatSurrealValue(ops.not)}`);
887
+ }
888
+ }
889
+ if (ops.between !== undefined && Array.isArray(ops.between) && ops.between.length === 2) {
890
+ conditions.push(`${columnName} >= ${this.formatSurrealValue(ops.between[0])} AND ${columnName} <= ${this.formatSurrealValue(ops.between[1])}`);
891
+ }
892
+ if (ops.gt !== undefined) {
893
+ conditions.push(`${columnName} > ${this.formatSurrealValue(ops.gt)}`);
894
+ }
895
+ if (ops.gte !== undefined) {
896
+ conditions.push(`${columnName} >= ${this.formatSurrealValue(ops.gte)}`);
897
+ }
898
+ if (ops.lt !== undefined) {
899
+ conditions.push(`${columnName} < ${this.formatSurrealValue(ops.lt)}`);
900
+ }
901
+ if (ops.lte !== undefined) {
902
+ conditions.push(`${columnName} <= ${this.formatSurrealValue(ops.lte)}`);
903
+ }
904
+ if (ops.contains !== undefined) {
905
+ conditions.push(`${columnName} CONTAINS ${this.formatSurrealValue(ops.contains)}`);
906
+ }
907
+ } else {
908
+ // Simple equality
909
+ conditions.push(`${columnName} = ${this.formatSurrealValue(condition)}`);
910
+ }
911
+ } else {
912
+ // Handle regular properties via graph traversal
913
+ const propMeta = metadata.properties[propertyName];
914
+ if (!propMeta) continue; // Skip if property not found in metadata
915
+
916
+ const predicate = propMeta.predicate;
917
+ // Use fn::parse_literal() for properties with resolveLanguage
918
+ const targetField = propMeta.resolveLanguage === 'literal' ? 'fn::parse_literal(out.uri)' : 'out.uri';
919
+
920
+ if (Array.isArray(condition)) {
921
+ // Array values (IN clause)
922
+ const formattedValues = condition.map(v => this.formatSurrealValue(v)).join(', ');
923
+ conditions.push(`count(->link[WHERE perspective = $perspective AND predicate = '${predicate}' AND ${targetField} IN [${formattedValues}]]) > 0`);
924
+ } else if (typeof condition === 'object' && condition !== null) {
925
+ // Operator object
926
+ const ops = condition as any;
927
+ if (ops.not !== undefined) {
928
+ if (Array.isArray(ops.not)) {
929
+ // For NOT IN with array: must NOT have a link with value in the array
930
+ const formattedValues = ops.not.map(v => this.formatSurrealValue(v)).join(', ');
931
+ conditions.push(`count(->link[WHERE perspective = $perspective AND predicate = '${predicate}' AND ${targetField} IN [${formattedValues}]]) = 0`);
932
+ } else {
933
+ // For NOT with single value: must NOT have this value
934
+ conditions.push(`count(->link[WHERE perspective = $perspective AND predicate = '${predicate}' AND ${targetField} = ${this.formatSurrealValue(ops.not)}]) = 0`);
935
+ }
936
+ }
937
+ // Note: gt, gte, lt, lte, between, contains operators are filtered in JavaScript
938
+ // post-query because fn::parse_literal() comparisons in SurrealDB
939
+ // don't work reliably with numeric comparisons.
940
+ // These are handled in instancesFromSurrealResult along with author/timestamp filtering.
941
+ // However, we still need to ensure the property exists
942
+ const hasComparisonOps = ops.gt !== undefined || ops.gte !== undefined ||
943
+ ops.lt !== undefined || ops.lte !== undefined ||
944
+ ops.between !== undefined || ops.contains !== undefined;
945
+ if (hasComparisonOps) {
946
+ // Ensure we only get nodes that have this property
947
+ conditions.push(`count(->link[WHERE perspective = $perspective AND predicate = '${predicate}']) > 0`);
948
+ }
949
+ } else {
950
+ // Simple equality
951
+ conditions.push(`count(->link[WHERE perspective = $perspective AND predicate = '${predicate}' AND ${targetField} = ${this.formatSurrealValue(condition)}]) > 0`);
952
+ }
953
+ }
954
+ }
955
+
956
+ return conditions.join(' AND ');
957
+ }
958
+
959
+ /**
960
+ * Builds the WHERE clause for SurrealQL queries.
961
+ *
962
+ * @description
963
+ * Translates the where conditions from the Query object into SurrealQL WHERE clause fragments.
964
+ * For each property filter, generates a subquery that checks for links with the appropriate
965
+ * predicate and target value.
966
+ *
967
+ * Handles several condition types:
968
+ * - Simple equality: `{ name: "Pasta" }` → subquery checking for predicate and target match
969
+ * - Arrays (IN clause): `{ name: ["Pasta", "Pizza"] }` → target IN [...]
970
+ * - Operators: `{ rating: { gt: 4 } }` → target > '4'
971
+ * - gt, gte, lt, lte: comparison operators
972
+ * - not: negation (single value or array)
973
+ * - between: range check
974
+ * - contains: substring/element check (uses SurrealQL CONTAINS)
975
+ * - Special fields: base, author, timestamp are accessed directly, not via subqueries
976
+ *
977
+ * All conditions are joined with AND.
978
+ *
979
+ * @param metadata - Model metadata containing property predicates
980
+ * @param where - Where conditions from the query
981
+ * @returns WHERE clause string (without the "WHERE" keyword), or empty string if no conditions
982
+ *
983
+ * @private
984
+ */
985
+ private static buildSurrealWhereClause(metadata: ModelMetadata, where?: Where): string {
986
+ if (!where) return '';
987
+
988
+ const conditions: string[] = [];
989
+
990
+ for (const [propertyName, condition] of Object.entries(where)) {
991
+ // Check if this is a special field (base, author, timestamp)
992
+ // Note: author and timestamp filtering is done in JavaScript after GROUP BY
993
+ // because they need to be computed from the grouped links first
994
+ const isSpecial = ['base', 'author', 'timestamp'].includes(propertyName);
995
+
996
+ if (isSpecial) {
997
+ // Skip author and timestamp - they'll be filtered in JavaScript
998
+ // Only handle 'base' (which maps to 'source') here
999
+ if (propertyName === 'author' || propertyName === 'timestamp') {
1000
+ continue; // Skip - will be filtered post-query
1001
+ }
1002
+
1003
+ const columnName = 'source'; // base maps to source
1004
+
1005
+ // Handle base/source field directly
1006
+ if (Array.isArray(condition)) {
1007
+ // Array values (IN clause)
1008
+ const formattedValues = condition.map(v => this.formatSurrealValue(v)).join(', ');
1009
+ conditions.push(`${columnName} IN [${formattedValues}]`);
1010
+ } else if (typeof condition === 'object' && condition !== null) {
1011
+ // Operator object
1012
+ const ops = condition as any;
1013
+ if (ops.not !== undefined) {
1014
+ if (Array.isArray(ops.not)) {
1015
+ const formattedValues = ops.not.map(v => this.formatSurrealValue(v)).join(', ');
1016
+ conditions.push(`${columnName} NOT IN [${formattedValues}]`);
1017
+ } else {
1018
+ conditions.push(`${columnName} != ${this.formatSurrealValue(ops.not)}`);
1019
+ }
1020
+ }
1021
+ if (ops.between !== undefined && Array.isArray(ops.between) && ops.between.length === 2) {
1022
+ conditions.push(`${columnName} >= ${this.formatSurrealValue(ops.between[0])} AND ${columnName} <= ${this.formatSurrealValue(ops.between[1])}`);
1023
+ }
1024
+ if (ops.gt !== undefined) {
1025
+ conditions.push(`${columnName} > ${this.formatSurrealValue(ops.gt)}`);
1026
+ }
1027
+ if (ops.gte !== undefined) {
1028
+ conditions.push(`${columnName} >= ${this.formatSurrealValue(ops.gte)}`);
1029
+ }
1030
+ if (ops.lt !== undefined) {
1031
+ conditions.push(`${columnName} < ${this.formatSurrealValue(ops.lt)}`);
1032
+ }
1033
+ if (ops.lte !== undefined) {
1034
+ conditions.push(`${columnName} <= ${this.formatSurrealValue(ops.lte)}`);
1035
+ }
1036
+ if (ops.contains !== undefined) {
1037
+ conditions.push(`${columnName} CONTAINS ${this.formatSurrealValue(ops.contains)}`);
1038
+ }
1039
+ } else {
1040
+ // Simple equality
1041
+ conditions.push(`${columnName} = ${this.formatSurrealValue(condition)}`);
1042
+ }
1043
+ } else {
1044
+ // Handle regular properties via subqueries
1045
+ const propMeta = metadata.properties[propertyName];
1046
+ if (!propMeta) continue; // Skip if property not found in metadata
1047
+
1048
+ const predicate = propMeta.predicate;
1049
+ // Use fn::parse_literal() for properties with resolveLanguage
1050
+ const targetField = propMeta.resolveLanguage === 'literal' ? 'fn::parse_literal(target)' : 'target';
1051
+
1052
+ if (Array.isArray(condition)) {
1053
+ // Array values (IN clause)
1054
+ const formattedValues = condition.map(v => this.formatSurrealValue(v)).join(', ');
1055
+ conditions.push(`source IN (SELECT VALUE source FROM link WHERE predicate = '${predicate}' AND ${targetField} IN [${formattedValues}])`);
1056
+ } else if (typeof condition === 'object' && condition !== null) {
1057
+ // Operator object
1058
+ const ops = condition as any;
1059
+ if (ops.not !== undefined) {
1060
+ if (Array.isArray(ops.not)) {
1061
+ // For NOT IN with array: exclude sources that HAVE a value in the array
1062
+ const formattedValues = ops.not.map(v => this.formatSurrealValue(v)).join(', ');
1063
+ conditions.push(`source NOT IN (SELECT VALUE source FROM link WHERE predicate = '${predicate}' AND ${targetField} IN [${formattedValues}])`);
1064
+ } else {
1065
+ // For NOT with single value: exclude sources that HAVE this value
1066
+ conditions.push(`source NOT IN (SELECT VALUE source FROM link WHERE predicate = '${predicate}' AND ${targetField} = ${this.formatSurrealValue(ops.not)})`);
1067
+ }
1068
+ }
1069
+ // Note: gt, gte, lt, lte, between, contains operators are filtered in JavaScript
1070
+ // post-query because fn::parse_literal() comparisons in SurrealDB subqueries
1071
+ // don't work reliably with numeric comparisons.
1072
+ // These are handled in instancesFromSurrealResult along with author/timestamp filtering.
1073
+ // However, we still need to ensure the property exists by filtering on the predicate
1074
+ const hasComparisonOps = ops.gt !== undefined || ops.gte !== undefined ||
1075
+ ops.lt !== undefined || ops.lte !== undefined ||
1076
+ ops.between !== undefined || ops.contains !== undefined;
1077
+ if (hasComparisonOps) {
1078
+ // Ensure we only get instances that have this property
1079
+ conditions.push(`source IN (SELECT VALUE source FROM link WHERE predicate = '${predicate}')`);
1080
+ }
1081
+ } else {
1082
+ // Simple equality
1083
+ conditions.push(`source IN (SELECT VALUE source FROM link WHERE predicate = '${predicate}' AND ${targetField} = ${this.formatSurrealValue(condition)})`);
1084
+ }
1085
+ }
1086
+ }
1087
+
1088
+ return conditions.join(' AND ');
1089
+ }
1090
+
1091
+ /**
1092
+ * Builds the SELECT fields for SurrealQL queries.
1093
+ *
1094
+ * @description
1095
+ * Generates the field list for the SELECT clause, resolving properties and collections
1096
+ * via subqueries. Each property is fetched with a subquery that finds the link with the
1097
+ * appropriate predicate and returns its target. Collections are similar but don't use LIMIT 1.
1098
+ *
1099
+ * Field types:
1100
+ * - Properties: `(SELECT VALUE target FROM link WHERE source = $parent.base AND predicate = 'X' LIMIT 1) AS propName`
1101
+ * - Collections: `(SELECT VALUE target FROM link WHERE source = $parent.base AND predicate = 'X') AS collName`
1102
+ * - Author/Timestamp: Always included to provide metadata about each instance
1103
+ *
1104
+ * If properties or collections arrays are provided, only those fields are included.
1105
+ * Otherwise, all properties/collections from metadata are included.
1106
+ *
1107
+ * @param metadata - Model metadata containing property and collection predicates
1108
+ * @param properties - Optional array of property names to include (default: all)
1109
+ * @param collections - Optional array of collection names to include (default: all)
1110
+ * @returns Comma-separated SELECT field list
1111
+ *
1112
+ * @private
1113
+ */
1114
+ private static buildSurrealSelectFields(metadata: ModelMetadata, properties?: string[], collections?: string[]): string {
1115
+ const fields: string[] = [];
1116
+
1117
+ // Determine properties to fetch
1118
+ const propsToFetch = properties || Object.keys(metadata.properties);
1119
+ for (const propName of propsToFetch) {
1120
+ const propMeta = metadata.properties[propName];
1121
+ if (!propMeta) continue; // Skip if not found
1122
+
1123
+ // Reference source directly since we're selecting from link table
1124
+ fields.push(`(SELECT VALUE target FROM link WHERE source = source AND predicate = '${propMeta.predicate}' LIMIT 1) AS ${propName}`);
1125
+ }
1126
+
1127
+ // Determine collections to fetch
1128
+ const collsToFetch = collections || Object.keys(metadata.collections);
1129
+ for (const collName of collsToFetch) {
1130
+ const collMeta = metadata.collections[collName];
1131
+ if (!collMeta) continue; // Skip if not found
1132
+
1133
+ // Reference source directly since we're selecting from link table
1134
+ fields.push(`(SELECT VALUE target FROM link WHERE source = source AND predicate = '${collMeta.predicate}') AS ${collName}`);
1135
+ }
1136
+
1137
+ // Always add author and timestamp fields
1138
+ fields.push(`(SELECT VALUE author FROM link WHERE source = source LIMIT 1) AS author`);
1139
+ fields.push(`(SELECT VALUE timestamp FROM link WHERE source = source LIMIT 1) AS timestamp`);
1140
+
1141
+ return fields.join(',\n ');
1142
+ }
1143
+
1144
+ /**
1145
+ * Builds the SELECT fields for SurrealQL queries using aggregation functions.
1146
+ * Compatible with GROUP BY source queries.
1147
+ *
1148
+ * @private
1149
+ */
1150
+ private static buildSurrealSelectFieldsWithAggregation(metadata: ModelMetadata, properties?: string[], collections?: string[]): string {
1151
+ const fields: string[] = [];
1152
+
1153
+ // Determine properties to fetch
1154
+ const propsToFetch = properties || Object.keys(metadata.properties);
1155
+ for (const propName of propsToFetch) {
1156
+ const propMeta = metadata.properties[propName];
1157
+ if (!propMeta) continue; // Skip if not found
1158
+
1159
+ // Use array::first to get the first target value for this predicate
1160
+ fields.push(`array::first(target[WHERE predicate = '${propMeta.predicate}']) AS ${propName}`);
1161
+ }
1162
+
1163
+ // Determine collections to fetch
1164
+ const collsToFetch = collections || Object.keys(metadata.collections);
1165
+ for (const collName of collsToFetch) {
1166
+ const collMeta = metadata.collections[collName];
1167
+ if (!collMeta) continue; // Skip if not found
1168
+
1169
+ // Use array filtering to get all target values for this predicate
1170
+ fields.push(`target[WHERE predicate = '${collMeta.predicate}'] AS ${collName}`);
1171
+ }
1172
+
1173
+ // Always add author and timestamp fields using array::first
1174
+ fields.push(`array::first(author) AS author`);
1175
+ fields.push(`array::first(timestamp) AS timestamp`);
1176
+
1177
+ return fields.join(',\n ');
1178
+ }
1179
+
1180
+
1181
+ /**
1182
+ * Formats a value for use in SurrealQL queries.
1183
+ *
1184
+ * @description
1185
+ * Handles different value types:
1186
+ * - Strings: Wrapped in single quotes with backslash-escaped special characters
1187
+ * - Numbers/booleans: Converted to string
1188
+ * - Arrays: Recursively formatted and wrapped in brackets
1189
+ *
1190
+ * @param value - The value to format
1191
+ * @returns Formatted value string ready for SurrealQL
1192
+ *
1193
+ * @private
1194
+ */
1195
+ private static formatSurrealValue(value: any): string {
1196
+ if (typeof value === 'string') {
1197
+ // Escape backslashes first, then single quotes and other special characters
1198
+ const escaped = value
1199
+ .replace(/\\/g, '\\\\') // Backslash -> \\
1200
+ .replace(/'/g, "\\'") // Single quote -> \'
1201
+ .replace(/"/g, '\\"') // Double quote -> \"
1202
+ .replace(/\n/g, '\\n') // Newline -> \n
1203
+ .replace(/\r/g, '\\r') // Carriage return -> \r
1204
+ .replace(/\t/g, '\\t'); // Tab -> \t
1205
+ return `'${escaped}'`;
1206
+ } else if (typeof value === 'number' || typeof value === 'boolean') {
1207
+ return String(value);
1208
+ } else if (Array.isArray(value)) {
1209
+ return `[${value.map(v => this.formatSurrealValue(v)).join(', ')}]`;
1210
+ } else {
1211
+ return String(value);
1212
+ }
1213
+ }
1214
+
446
1215
  public static async instancesFromPrologResult<T extends Ad4mModel>(
447
1216
  this: typeof Ad4mModel & (new (...args: any[]) => T),
448
1217
  perspective: PerspectiveProxy,
@@ -477,19 +1246,370 @@ export class Ad4mModel {
477
1246
  return { results: allInstances.filter((instance) => instance !== null), totalCount: result[0].TotalCount };
478
1247
  }
479
1248
 
1249
+ /**
1250
+ * Converts SurrealDB query results to Ad4mModel instances.
1251
+ *
1252
+ * @param perspective - The perspective context
1253
+ * @param query - The query parameters used
1254
+ * @param result - Array of result objects from SurrealDB
1255
+ * @returns Promise resolving to results with total count
1256
+ *
1257
+ * @internal
1258
+ */
1259
+ public static async instancesFromSurrealResult<T extends Ad4mModel>(
1260
+ this: typeof Ad4mModel & (new (...args: any[]) => T),
1261
+ perspective: PerspectiveProxy,
1262
+ query: Query,
1263
+ result: any[]
1264
+ ): Promise<ResultsWithTotalCount<T>> {
1265
+ if (!result || result.length === 0) return { results: [], totalCount: 0 };
1266
+
1267
+ const metadata = this.getModelMetadata();
1268
+ const requestedProperties = query?.properties || [];
1269
+ const requestedCollections = query?.collections || [];
1270
+
1271
+ // The query used GROUP BY with graph traversal, so each row has:
1272
+ // - source: the node ID (e.g., "node:abc123")
1273
+ // - source_uri: the actual URI (the base expression)
1274
+ // - links: array of link objects with {predicate, target, author, timestamp}
1275
+
1276
+ const instances: T[] = [];
1277
+ for (const row of result) {
1278
+ let base;
1279
+ try {
1280
+ // Use source_uri as the base (the actual URI), not the node ID
1281
+ base = row.source_uri;
1282
+
1283
+ // Skip rows without a source_uri field
1284
+ if (!base) {
1285
+ continue;
1286
+ }
1287
+
1288
+ const links = row.links || [];
1289
+
1290
+ const instance = new this(perspective, base) as any;
1291
+
1292
+ // Track the most recent timestamp and corresponding author
1293
+ let maxTimestamp = null;
1294
+ let latestAuthor = null;
1295
+
1296
+ // Process each link (track index for collection ordering)
1297
+ for (let linkIndex = 0; linkIndex < links.length; linkIndex++) {
1298
+ const link = links[linkIndex];
1299
+ const predicate = link.predicate;
1300
+ const target = link.target;
1301
+
1302
+ // Skip 'None' values
1303
+ if (target === 'None') continue;
1304
+
1305
+ // Track the most recent timestamp and its author
1306
+ if (link.timestamp && (!maxTimestamp || link.timestamp > maxTimestamp)) {
1307
+ maxTimestamp = link.timestamp;
1308
+ latestAuthor = link.author;
1309
+ }
1310
+
1311
+ // Find matching property
1312
+ let foundProperty = false;
1313
+ for (const [propName, propMeta] of Object.entries(metadata.properties)) {
1314
+ if (propMeta.predicate === predicate) {
1315
+ // For properties, take the first value (or we could use timestamp to get latest)
1316
+ // Note: Empty objects {} are truthy, so we need to check for them explicitly
1317
+ const currentValue = instance[propName];
1318
+ const isEmptyObject = typeof currentValue === 'object' && currentValue !== null && !Array.isArray(currentValue) && Object.keys(currentValue).length === 0;
1319
+ if (!currentValue || currentValue === "" || currentValue === 0 || isEmptyObject) {
1320
+ let convertedValue = target;
1321
+
1322
+ // Parse literal URLs if property has resolveLanguage
1323
+ if (propMeta.resolveLanguage === 'literal' && typeof target === 'string' && target.startsWith('literal://')) {
1324
+ try {
1325
+ convertedValue = Literal.fromUrl(target).get();
1326
+ if(convertedValue.data !== undefined) {
1327
+ convertedValue = convertedValue.data;
1328
+ }
1329
+ } catch (e) {
1330
+ console.warn(`Failed to parse literal URL for ${propName}:`, e);
1331
+ convertedValue = target; // Fall back to raw value
1332
+ }
1333
+ } else {
1334
+ // Type conversion: check the instance property's current type
1335
+ const expectedType = typeof instance[propName];
1336
+ if (expectedType === 'number' && typeof target === 'string') {
1337
+ convertedValue = Number(target);
1338
+ } else if (expectedType === 'boolean' && typeof target === 'string') {
1339
+ convertedValue = target === 'true' || target === '1';
1340
+ }
1341
+ }
1342
+
1343
+ // Apply transform function if it exists
1344
+ if (propMeta.transform && typeof propMeta.transform === 'function') {
1345
+ convertedValue = propMeta.transform(convertedValue);
1346
+ }
1347
+
1348
+ instance[propName] = convertedValue;
1349
+ }
1350
+ foundProperty = true;
1351
+ break;
1352
+ }
1353
+ }
1354
+
1355
+ // If not a property, check if it's a collection
1356
+ if (!foundProperty) {
1357
+ for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1358
+ if (collMeta.predicate === predicate) {
1359
+ // For collections, accumulate all values with their timestamps and indices for sorting
1360
+ if (!instance[collName]) {
1361
+ instance[collName] = [];
1362
+ }
1363
+ // Initialize timestamp tracking array if not already done
1364
+ const timestampsKey = `__${collName}_timestamps`;
1365
+ const indicesKey = `__${collName}_indices`;
1366
+ if (!instance[timestampsKey]) {
1367
+ instance[timestampsKey] = [];
1368
+ }
1369
+ if (!instance[indicesKey]) {
1370
+ instance[indicesKey] = [];
1371
+ }
1372
+ if (!instance[collName].includes(target)) {
1373
+ instance[collName].push(target);
1374
+ instance[timestampsKey].push(link.timestamp || '');
1375
+ // Track original position in the links array for stable sorting
1376
+ instance[indicesKey].push(linkIndex);
1377
+ }
1378
+ break;
1379
+ }
1380
+ }
1381
+ }
1382
+ }
1383
+
1384
+ // Set author and timestamp from the most recent link
1385
+ if (latestAuthor && maxTimestamp) {
1386
+ instance.author = latestAuthor;
1387
+ // Convert timestamp to number (milliseconds) if it's an ISO string
1388
+ if (typeof maxTimestamp === 'string' && maxTimestamp.includes('T')) {
1389
+ instance.timestamp = new Date(maxTimestamp).getTime();
1390
+ } else if (typeof maxTimestamp === 'string') {
1391
+ // Try to parse as number string
1392
+ const parsed = parseInt(maxTimestamp, 10);
1393
+ instance.timestamp = isNaN(parsed) ? maxTimestamp : parsed;
1394
+ } else {
1395
+ instance.timestamp = maxTimestamp;
1396
+ }
1397
+ }
1398
+
1399
+ // Sort collections by timestamp to maintain insertion order
1400
+ for (const [collName, collMeta] of Object.entries(metadata.collections)) {
1401
+ const timestampsKey = `__${collName}_timestamps`;
1402
+ const indicesKey = `__${collName}_indices`;
1403
+ if (instance[collName] && instance[timestampsKey]) {
1404
+ // Create array of [value, timestamp, index] tuples
1405
+ const pairs = instance[collName].map((value: any, index: number) => ({
1406
+ value,
1407
+ timestamp: instance[timestampsKey][index] || '',
1408
+ originalIndex: instance[indicesKey]?.[index] ?? index
1409
+ }));
1410
+ // Sort by timestamp first, then by original index for stable sorting
1411
+ pairs.sort((a, b) => {
1412
+ const tsA = String(a.timestamp || '');
1413
+ const tsB = String(b.timestamp || '');
1414
+ const tsCompare = tsA.localeCompare(tsB);
1415
+ if (tsCompare !== 0) return tsCompare;
1416
+ // Use original index as tiebreaker for stable sorting
1417
+ return a.originalIndex - b.originalIndex;
1418
+ });
1419
+ // Replace collection with sorted values
1420
+ instance[collName] = pairs.map(p => p.value);
1421
+ // Clean up temporary arrays
1422
+ delete instance[timestampsKey];
1423
+ delete instance[indicesKey];
1424
+ }
1425
+ }
1426
+
1427
+ // Filter by requested attributes if specified
1428
+ if (requestedProperties.length > 0 || requestedCollections.length > 0) {
1429
+ const requestedAttributes = [...requestedProperties, ...requestedCollections];
1430
+ Object.keys(instance).forEach((key) => {
1431
+ // Keep only requested attributes, plus always keep timestamp and author
1432
+ if (!requestedAttributes.includes(key) && key !== 'timestamp' && key !== 'author' && key !== 'baseExpression') {
1433
+ delete instance[key];
1434
+ }
1435
+ });
1436
+ }
1437
+
1438
+ instances.push(instance);
1439
+ } catch (error) {
1440
+ console.error(`Failed to process SurrealDB instance ${base}:`, error);
1441
+ }
1442
+ }
1443
+
1444
+ // Filter by where conditions that couldn't be filtered in SQL
1445
+ // This includes:
1446
+ // - author/timestamp (computed from grouped links)
1447
+ // - Properties with comparison operators (gt, gte, lt, lte, between, contains)
1448
+ // because fn::parse_literal() comparisons in SurrealDB subqueries don't work reliably
1449
+ let filteredInstances = instances;
1450
+ if (query.where) {
1451
+ filteredInstances = instances.filter(instance => {
1452
+ for (const [propertyName, condition] of Object.entries(query.where!)) {
1453
+ // Skip 'base' as it's filtered in SQL
1454
+ if (propertyName === 'base') continue;
1455
+
1456
+ // For author and timestamp, always filter in JS
1457
+ if (propertyName === 'author' || propertyName === 'timestamp') {
1458
+ if (!this.matchesCondition(instance[propertyName], condition)) {
1459
+ return false;
1460
+ }
1461
+ continue;
1462
+ }
1463
+
1464
+ // For regular properties, only filter comparison operators in JS
1465
+ // Simple equality and NOT are handled in SQL, but gt/gte/lt/lte/between/contains need JS
1466
+ if (typeof condition === 'object' && condition !== null && !Array.isArray(condition)) {
1467
+ const ops = condition as any;
1468
+ // Check if any comparison operators are present
1469
+ const hasComparisonOps = ops.gt !== undefined || ops.gte !== undefined ||
1470
+ ops.lt !== undefined || ops.lte !== undefined ||
1471
+ ops.between !== undefined || ops.contains !== undefined;
1472
+ if (hasComparisonOps) {
1473
+ if (!this.matchesCondition(instance[propertyName], condition)) {
1474
+ return false;
1475
+ }
1476
+ }
1477
+ }
1478
+ }
1479
+ return true;
1480
+ });
1481
+ }
1482
+
1483
+ // Apply ordering in JavaScript
1484
+ // If limit/offset is used but no explicit order, default to ordering by timestamp (ASC)
1485
+ // This ensures consistent pagination behavior
1486
+ const effectiveOrder = query.order ||
1487
+ (query.limit !== undefined || query.offset !== undefined ? { timestamp: 'ASC' as 'ASC' } : null);
1488
+
1489
+ if (effectiveOrder) {
1490
+ const orderPropName = Object.keys(effectiveOrder)[0];
1491
+ const orderDirection = Object.values(effectiveOrder)[0];
1492
+
1493
+ filteredInstances.sort((a: any, b: any) => {
1494
+ let aVal = a[orderPropName];
1495
+ let bVal = b[orderPropName];
1496
+
1497
+ // Handle undefined values - push them to the end
1498
+ if (aVal === undefined && bVal === undefined) return 0;
1499
+ if (aVal === undefined) return orderDirection === 'ASC' ? 1 : -1;
1500
+ if (bVal === undefined) return orderDirection === 'ASC' ? -1 : 1;
1501
+
1502
+ // Compare values
1503
+ let comparison = 0;
1504
+ if (typeof aVal === 'number' && typeof bVal === 'number') {
1505
+ comparison = aVal - bVal;
1506
+ } else if (typeof aVal === 'string' && typeof bVal === 'string') {
1507
+ comparison = aVal.localeCompare(bVal);
1508
+ } else {
1509
+ // Convert to strings for comparison
1510
+ comparison = String(aVal).localeCompare(String(bVal));
1511
+ }
1512
+
1513
+ return orderDirection === 'DESC' ? -comparison : comparison;
1514
+ });
1515
+ }
1516
+
1517
+ // Calculate totalCount BEFORE applying limit/offset
1518
+ const totalCount = filteredInstances.length;
1519
+
1520
+ // Apply offset and limit in JavaScript
1521
+ let paginatedInstances = filteredInstances;
1522
+ if (query.offset !== undefined || query.limit !== undefined) {
1523
+ const start = query.offset || 0;
1524
+ const end = query.limit ? start + query.limit : undefined;
1525
+ paginatedInstances = filteredInstances.slice(start, end);
1526
+ }
1527
+
1528
+ return {
1529
+ results: paginatedInstances,
1530
+ totalCount
1531
+ };
1532
+ }
1533
+
1534
+ /**
1535
+ * Checks if a value matches a condition (for post-query filtering).
1536
+ * @private
1537
+ */
1538
+ private static matchesCondition(value: any, condition: WhereCondition): boolean {
1539
+ // Handle array values (IN clause)
1540
+ if (Array.isArray(condition)) {
1541
+ return (condition as any[]).includes(value);
1542
+ }
1543
+
1544
+ // Handle operator object
1545
+ if (typeof condition === 'object' && condition !== null) {
1546
+ const ops = condition as any;
1547
+
1548
+ // Special case: 'not' operator (exclusive with other operators)
1549
+ if (ops.not !== undefined) {
1550
+ if (Array.isArray(ops.not)) {
1551
+ return !(ops.not as any[]).includes(value);
1552
+ } else {
1553
+ return value !== ops.not;
1554
+ }
1555
+ }
1556
+
1557
+ // Special case: 'between' operator (inclusive range, exclusive with gt/gte/lt/lte)
1558
+ if (ops.between !== undefined && Array.isArray(ops.between) && ops.between.length === 2) {
1559
+ return value >= ops.between[0] && value <= ops.between[1];
1560
+ }
1561
+
1562
+ // For all other operators (gt, gte, lt, lte, contains), we need to check ALL of them
1563
+ // and return true only if ALL conditions are satisfied
1564
+ let allConditionsMet = true;
1565
+
1566
+ if (ops.gt !== undefined) {
1567
+ allConditionsMet = allConditionsMet && (value > ops.gt);
1568
+ }
1569
+
1570
+ if (ops.gte !== undefined) {
1571
+ allConditionsMet = allConditionsMet && (value >= ops.gte);
1572
+ }
1573
+
1574
+ if (ops.lt !== undefined) {
1575
+ allConditionsMet = allConditionsMet && (value < ops.lt);
1576
+ }
1577
+
1578
+ if (ops.lte !== undefined) {
1579
+ allConditionsMet = allConditionsMet && (value <= ops.lte);
1580
+ }
1581
+
1582
+ if (ops.contains !== undefined) {
1583
+ if (typeof value === 'string') {
1584
+ allConditionsMet = allConditionsMet && value.includes(String(ops.contains));
1585
+ } else if (Array.isArray(value)) {
1586
+ allConditionsMet = allConditionsMet && value.includes(ops.contains);
1587
+ } else {
1588
+ allConditionsMet = false;
1589
+ }
1590
+ }
1591
+
1592
+ return allConditionsMet;
1593
+ }
1594
+
1595
+ // Simple equality
1596
+ return value === condition;
1597
+ }
1598
+
480
1599
  /**
481
1600
  * Gets all instances of the model in the perspective that match the query params.
482
1601
  *
483
1602
  * @param perspective - The perspective to search in
484
1603
  * @param query - Optional query parameters to filter results
1604
+ * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
485
1605
  * @returns Array of matching models
486
1606
  *
487
1607
  * @example
488
1608
  * ```typescript
489
- * // Get all recipes
1609
+ * // Get all recipes (uses SurrealDB by default)
490
1610
  * const allRecipes = await Recipe.findAll(perspective);
491
1611
  *
492
- * // Get recipes with specific criteria
1612
+ * // Get recipes with specific criteria (uses SurrealDB)
493
1613
  * const recipes = await Recipe.findAll(perspective, {
494
1614
  * where: {
495
1615
  * name: "Pasta",
@@ -498,17 +1618,28 @@ export class Ad4mModel {
498
1618
  * order: { createdAt: "DESC" },
499
1619
  * limit: 10
500
1620
  * });
1621
+ *
1622
+ * // Explicitly use Prolog (legacy, for backward compatibility)
1623
+ * const recipesProlog = await Recipe.findAll(perspective, {}, false);
501
1624
  * ```
502
1625
  */
503
1626
  static async findAll<T extends Ad4mModel>(
504
1627
  this: typeof Ad4mModel & (new (...args: any[]) => T),
505
1628
  perspective: PerspectiveProxy,
506
- query: Query = {}
1629
+ query: Query = {},
1630
+ useSurrealDB: boolean = true
507
1631
  ): Promise<T[]> {
508
- const prologQuery = await this.queryToProlog(perspective, query);
509
- const result = await perspective.infer(prologQuery);
510
- const { results } = await this.instancesFromPrologResult(perspective, query, result);
511
- return results;
1632
+ if (useSurrealDB) {
1633
+ const surrealQuery = await this.queryToSurrealQL(perspective, query);
1634
+ const result = await perspective.querySurrealDB(surrealQuery);
1635
+ const { results } = await this.instancesFromSurrealResult(perspective, query, result);
1636
+ return results;
1637
+ } else {
1638
+ const prologQuery = await this.queryToProlog(perspective, query);
1639
+ const result = await perspective.infer(prologQuery);
1640
+ const { results } = await this.instancesFromPrologResult(perspective, query, result);
1641
+ return results;
1642
+ }
512
1643
  }
513
1644
 
514
1645
  /**
@@ -516,6 +1647,7 @@ export class Ad4mModel {
516
1647
  *
517
1648
  * @param perspective - The perspective to search in
518
1649
  * @param query - Optional query parameters to filter results
1650
+ * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
519
1651
  * @returns Object containing results array and total count
520
1652
  *
521
1653
  * @example
@@ -525,16 +1657,26 @@ export class Ad4mModel {
525
1657
  * limit: 10
526
1658
  * });
527
1659
  * console.log(`Showing 10 of ${totalCount} dessert recipes`);
1660
+ *
1661
+ * // Use Prolog explicitly (legacy)
1662
+ * const { results, totalCount } = await Recipe.findAllAndCount(perspective, {}, false);
528
1663
  * ```
529
1664
  */
530
1665
  static async findAllAndCount<T extends Ad4mModel>(
531
1666
  this: typeof Ad4mModel & (new (...args: any[]) => T),
532
1667
  perspective: PerspectiveProxy,
533
- query: Query = {}
1668
+ query: Query = {},
1669
+ useSurrealDB: boolean = true
534
1670
  ): Promise<ResultsWithTotalCount<T>> {
535
- const prologQuery = await this.queryToProlog(perspective, query);
536
- const result = await perspective.infer(prologQuery);
537
- return await this.instancesFromPrologResult(perspective, query, result);
1671
+ if (useSurrealDB) {
1672
+ const surrealQuery = await this.queryToSurrealQL(perspective, query);
1673
+ const result = await perspective.querySurrealDB(surrealQuery);
1674
+ return await this.instancesFromSurrealResult(perspective, query, result);
1675
+ } else {
1676
+ const prologQuery = await this.queryToProlog(perspective, query);
1677
+ const result = await perspective.infer(prologQuery);
1678
+ return await this.instancesFromPrologResult(perspective, query, result);
1679
+ }
538
1680
  }
539
1681
 
540
1682
  /**
@@ -544,6 +1686,7 @@ export class Ad4mModel {
544
1686
  * @param pageSize - Number of items per page
545
1687
  * @param pageNumber - Which page to retrieve (1-based)
546
1688
  * @param query - Optional additional query parameters
1689
+ * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
547
1690
  * @returns Paginated results with metadata
548
1691
  *
549
1692
  * @example
@@ -552,6 +1695,9 @@ export class Ad4mModel {
552
1695
  * where: { category: "Main Course" }
553
1696
  * });
554
1697
  * console.log(`Page ${page.pageNumber} of recipes, ${page.results.length} items`);
1698
+ *
1699
+ * // Use Prolog explicitly (legacy)
1700
+ * const pageProlog = await Recipe.paginate(perspective, 10, 1, {}, false);
555
1701
  * ```
556
1702
  */
557
1703
  static async paginate<T extends Ad4mModel>(
@@ -559,13 +1705,21 @@ export class Ad4mModel {
559
1705
  perspective: PerspectiveProxy,
560
1706
  pageSize: number,
561
1707
  pageNumber: number,
562
- query?: Query
1708
+ query?: Query,
1709
+ useSurrealDB: boolean = true
563
1710
  ): Promise<PaginationResult<T>> {
564
1711
  const paginationQuery = { ...(query || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
565
- const prologQuery = await this.queryToProlog(perspective, paginationQuery);
566
- const result = await perspective.infer(prologQuery);
567
- const { results, totalCount } = await this.instancesFromPrologResult(perspective, paginationQuery, result);
568
- return { results, totalCount, pageSize, pageNumber };
1712
+ if (useSurrealDB) {
1713
+ const surrealQuery = await this.queryToSurrealQL(perspective, paginationQuery);
1714
+ const result = await perspective.querySurrealDB(surrealQuery);
1715
+ const { results, totalCount } = await this.instancesFromSurrealResult(perspective, paginationQuery, result);
1716
+ return { results, totalCount, pageSize, pageNumber };
1717
+ } else {
1718
+ const prologQuery = await this.queryToProlog(perspective, paginationQuery);
1719
+ const result = await perspective.infer(prologQuery);
1720
+ const { results, totalCount } = await this.instancesFromPrologResult(perspective, paginationQuery, result);
1721
+ return { results, totalCount, pageSize, pageNumber };
1722
+ }
569
1723
  }
570
1724
 
571
1725
  static async countQueryToProlog(perspective: PerspectiveProxy, query: Query = {}, modelClassName?: string | null) {
@@ -586,11 +1740,30 @@ export class Ad4mModel {
586
1740
  return fullQuery;
587
1741
  }
588
1742
 
1743
+ /**
1744
+ * Generates a SurrealQL COUNT query for the model.
1745
+ *
1746
+ * @param perspective - The perspective context
1747
+ * @param query - Query parameters to filter the count
1748
+ * @returns SurrealQL COUNT query string
1749
+ *
1750
+ * @private
1751
+ */
1752
+ public static async countQueryToSurrealQL(perspective: PerspectiveProxy, query: Query): Promise<string> {
1753
+ // Use the same query as the main query (with GROUP BY), just without LIMIT/OFFSET
1754
+ // We'll count the number of rows returned (one row per source)
1755
+ const countQuery = { ...query };
1756
+ delete countQuery.limit;
1757
+ delete countQuery.offset;
1758
+ return await this.queryToSurrealQL(perspective, countQuery);
1759
+ }
1760
+
589
1761
  /**
590
1762
  * Gets a count of all matching instances.
591
1763
  *
592
1764
  * @param perspective - The perspective to search in
593
1765
  * @param query - Optional query parameters to filter results
1766
+ * @param useSurrealDB - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
594
1767
  * @returns Total count of matching entities
595
1768
  *
596
1769
  * @example
@@ -599,12 +1772,24 @@ export class Ad4mModel {
599
1772
  * const activeRecipes = await Recipe.count(perspective, {
600
1773
  * where: { status: "active" }
601
1774
  * });
1775
+ *
1776
+ * // Use Prolog explicitly (legacy)
1777
+ * const countProlog = await Recipe.count(perspective, {}, false);
602
1778
  * ```
603
1779
  */
604
- static async count(perspective: PerspectiveProxy, query: Query = {}) {
605
- const result = await perspective.infer(await this.countQueryToProlog(perspective, query));
606
-
607
- return result?.[0]?.TotalCount || 0;
1780
+ static async count(perspective: PerspectiveProxy, query: Query = {}, useSurrealDB: boolean = true) {
1781
+ if (useSurrealDB) {
1782
+ const surrealQuery = await this.queryToSurrealQL(perspective, query);
1783
+ const result = await perspective.querySurrealDB(surrealQuery);
1784
+ // Use instancesFromSurrealResult to apply JS-level filtering for advanced where conditions
1785
+ // (e.g., gt, gte, lt, lte, between, contains on properties and author/timestamp)
1786
+ // This ensures count() returns the same number as findAll().length
1787
+ const { totalCount } = await this.instancesFromSurrealResult(perspective, query, result);
1788
+ return totalCount;
1789
+ } else {
1790
+ const result = await perspective.infer(await this.countQueryToProlog(perspective, query));
1791
+ return result?.[0]?.TotalCount || 0;
1792
+ }
608
1793
  }
609
1794
 
610
1795
  private async setProperty(key: string, value: any, batchId?: string) {
@@ -899,6 +2084,368 @@ export class Ad4mModel {
899
2084
  ): ModelQueryBuilder<T> {
900
2085
  return new ModelQueryBuilder<T>(perspective, this as any, query);
901
2086
  }
2087
+
2088
+ /**
2089
+ * Creates an Ad4mModel class from a JSON Schema definition.
2090
+ *
2091
+ * @description
2092
+ * This method dynamically generates an Ad4mModel subclass from a JSON Schema,
2093
+ * enabling integration with systems that use JSON Schema for type definitions.
2094
+ *
2095
+ * The method follows a cascading approach for determining predicates:
2096
+ * 1. Explicit configuration in options parameter (highest precedence)
2097
+ * 2. x-ad4m metadata in the JSON Schema
2098
+ * 3. Inference from schema title and property names
2099
+ * 4. Error if no namespace can be determined
2100
+ *
2101
+ * @example
2102
+ * ```typescript
2103
+ * // With explicit configuration
2104
+ * const PersonClass = Ad4mModel.fromJSONSchema(schema, {
2105
+ * name: "Person",
2106
+ * namespace: "person://",
2107
+ * resolveLanguage: "literal"
2108
+ * });
2109
+ *
2110
+ * // With property mapping
2111
+ * const ContactClass = Ad4mModel.fromJSONSchema(schema, {
2112
+ * name: "Contact",
2113
+ * namespace: "contact://",
2114
+ * propertyMapping: {
2115
+ * "name": "foaf://name",
2116
+ * "email": "foaf://mbox"
2117
+ * }
2118
+ * });
2119
+ *
2120
+ * // With x-ad4m metadata in schema
2121
+ * const schema = {
2122
+ * "title": "Product",
2123
+ * "x-ad4m": { "namespace": "product://" },
2124
+ * "properties": {
2125
+ * "name": {
2126
+ * "type": "string",
2127
+ * "x-ad4m": { "through": "product://title" }
2128
+ * }
2129
+ * }
2130
+ * };
2131
+ * const ProductClass = Ad4mModel.fromJSONSchema(schema, { name: "Product" });
2132
+ * ```
2133
+ *
2134
+ * @param schema - JSON Schema definition
2135
+ * @param options - Configuration options
2136
+ * @returns Generated Ad4mModel subclass
2137
+ * @throws Error when namespace cannot be inferred
2138
+ */
2139
+ static fromJSONSchema(
2140
+ schema: JSONSchema,
2141
+ options: JSONSchemaToModelOptions
2142
+ ): typeof Ad4mModel {
2143
+ // Disallow top-level "author" property since Ad4mModel provides it implicitly via link authorship
2144
+ if (schema?.properties && Object.prototype.hasOwnProperty.call(schema.properties, "author")) {
2145
+ throw new Error('JSON Schema must not define a top-level "author" property because Ad4mModel already exposes it. Please rename the property (e.g., "writer").');
2146
+ }
2147
+ // Determine namespace with cascading precedence
2148
+ const namespace = this.determineNamespace(schema, options);
2149
+
2150
+ // Create the dynamic class
2151
+ const DynamicModelClass = class extends Ad4mModel {};
2152
+
2153
+ // Set up class metadata
2154
+ if (!options.name || options.name.trim() === '') {
2155
+ throw new Error("options.name is required and cannot be empty");
2156
+ }
2157
+ (DynamicModelClass as any).className = options.name;
2158
+ (DynamicModelClass.prototype as any).className = options.name;
2159
+
2160
+ // Generate properties and collections metadata
2161
+ const properties: any = {};
2162
+ const collections: any = {};
2163
+
2164
+ if (schema.properties) {
2165
+ for (const [propertyName, propertySchema] of Object.entries(schema.properties)) {
2166
+ const predicate = this.determinePredicate(schema, propertyName, propertySchema, namespace, options);
2167
+ const isRequired = schema.required?.includes(propertyName) || false;
2168
+ const propertyType = normalizeSchemaType(propertySchema.type);
2169
+ const isArray = isArrayType(propertySchema);
2170
+
2171
+ if (isArray) {
2172
+ // Handle arrays as collections
2173
+ // Store the singular form as the collection key since SDNA generation expects singular
2174
+ collections[propertyName] = {
2175
+ through: predicate,
2176
+ local: this.getPropertyOption(propertyName, propertySchema, options, 'local')
2177
+ };
2178
+
2179
+ // Define the property on prototype
2180
+ Object.defineProperty(DynamicModelClass.prototype, propertyName, {
2181
+ configurable: true,
2182
+ writable: true,
2183
+ value: []
2184
+ });
2185
+
2186
+ // Add collection methods
2187
+ const adderName = `add${capitalize(propertyName)}`;
2188
+ const removerName = `remove${capitalize(propertyName)}`;
2189
+ const setterName = `setCollection${capitalize(propertyName)}`;
2190
+
2191
+ (DynamicModelClass.prototype as any)[adderName] = function() {
2192
+ // Placeholder function for SDNA generation
2193
+ };
2194
+ (DynamicModelClass.prototype as any)[removerName] = function() {
2195
+ // Placeholder function for SDNA generation
2196
+ };
2197
+ (DynamicModelClass.prototype as any)[setterName] = function() {
2198
+ // Placeholder function for SDNA generation
2199
+ };
2200
+
2201
+ } else {
2202
+ // Handle regular properties
2203
+ let resolveLanguage = this.getPropertyOption(propertyName, propertySchema, options, 'resolveLanguage');
2204
+ // If no specific resolveLanguage for this property, use the global one
2205
+ if (!resolveLanguage && options.resolveLanguage) {
2206
+ resolveLanguage = options.resolveLanguage;
2207
+ }
2208
+ const local = this.getPropertyOption(propertyName, propertySchema, options, 'local');
2209
+ const writable = this.getPropertyOption(propertyName, propertySchema, options, 'writable', true);
2210
+ let initial = this.getPropertyOption(propertyName, propertySchema, options, 'initial');
2211
+
2212
+ // Handle nested objects by serializing to JSON
2213
+ if (isObjectType(propertySchema) && !resolveLanguage) {
2214
+ resolveLanguage = 'literal';
2215
+ console.warn(`Property "${propertyName}" is an object type. It will be stored as JSON. Consider flattening complex objects for better semantic querying.`);
2216
+ }
2217
+
2218
+ // Ensure numeric properties use literal language for correct typing
2219
+ if ((resolveLanguage === undefined || resolveLanguage === null) && isNumericType(propertySchema)) {
2220
+ resolveLanguage = 'literal';
2221
+ }
2222
+
2223
+ // If property is required, ensure it has an initial value
2224
+ if (isRequired && !initial) {
2225
+ if (isObjectType(propertySchema)) {
2226
+ initial = 'literal://json:{}';
2227
+ } else {
2228
+ initial = "ad4m://undefined";
2229
+ }
2230
+ }
2231
+
2232
+ properties[propertyName] = {
2233
+ through: predicate,
2234
+ required: isRequired,
2235
+ writable: writable,
2236
+ ...(resolveLanguage && { resolveLanguage }),
2237
+ ...(local !== undefined && { local }),
2238
+ ...(initial && { initial })
2239
+ };
2240
+
2241
+ // Define the property on prototype
2242
+ Object.defineProperty(DynamicModelClass.prototype, propertyName, {
2243
+ configurable: true,
2244
+ writable: true,
2245
+ value: this.getDefaultValueForType(propertyType)
2246
+ });
2247
+
2248
+ // Add setter function if writable
2249
+ if (writable) {
2250
+ const setterName = propertyNameToSetterName(propertyName);
2251
+ (DynamicModelClass.prototype as any)[setterName] = function() {
2252
+ // This is a placeholder function that the SDNA generation looks for
2253
+ // The actual setter logic is handled by the Ad4mModel base class
2254
+ };
2255
+ }
2256
+ }
2257
+ }
2258
+ }
2259
+
2260
+ // Validate that at least one property has an initial value (needed for valid SDNA constructor)
2261
+ // Collections don't create constructor actions, only properties with initial values do
2262
+ const hasPropertyWithInitial = Object.values(properties).some((prop: any) => prop.initial);
2263
+
2264
+ if (!hasPropertyWithInitial) {
2265
+ // If no properties have initial values, add a type identifier automatically
2266
+ const typeProperty = `ad4m://type`;
2267
+ let typeValue: string;
2268
+ if (namespace.includes('://')) {
2269
+ const [scheme, rest] = namespace.split('://');
2270
+ const path = (rest || '').replace(/\/+$/,'');
2271
+ if (path) {
2272
+ typeValue = `${scheme}://${path}/instance`;
2273
+ } else {
2274
+ typeValue = `${scheme}://instance`;
2275
+ }
2276
+ } else {
2277
+ const path = namespace.replace(/\/+$/,'');
2278
+ typeValue = `${path}/instance`;
2279
+ }
2280
+
2281
+ properties['__ad4m_type'] = {
2282
+ through: typeProperty,
2283
+ required: true,
2284
+ writable: false,
2285
+ initial: typeValue,
2286
+ flag: true
2287
+ };
2288
+
2289
+ // Add the type property to the prototype
2290
+ Object.defineProperty(DynamicModelClass.prototype, '__ad4m_type', {
2291
+ configurable: true,
2292
+ writable: false,
2293
+ value: typeValue
2294
+ });
2295
+
2296
+ console.warn(`No properties with initial values found. Added automatic type flag: ${typeProperty} = ${typeValue}`);
2297
+ }
2298
+
2299
+ // Attach metadata to prototype
2300
+ (DynamicModelClass.prototype as any).__properties = properties;
2301
+ (DynamicModelClass.prototype as any).__collections = collections;
2302
+
2303
+ // Store the JSON schema and options on the prototype for potential fallback use by getModelMetadata()
2304
+ (DynamicModelClass.prototype as any).__jsonSchema = schema;
2305
+ (DynamicModelClass.prototype as any).__jsonSchemaOptions = options;
2306
+
2307
+ // Apply the ModelOptions decorator to set up the generateSDNA method
2308
+ const ModelOptionsDecorator = ModelOptions({ name: options.name });
2309
+ ModelOptionsDecorator(DynamicModelClass);
2310
+
2311
+ return DynamicModelClass as typeof Ad4mModel;
2312
+ }
2313
+
2314
+ /**
2315
+ * Determines the namespace for predicates using cascading precedence
2316
+ */
2317
+ private static determineNamespace(schema: JSONSchema, options: JSONSchemaToModelOptions): string {
2318
+ // 1. Explicit namespace in options (highest precedence)
2319
+ if (options.namespace) {
2320
+ return options.namespace;
2321
+ }
2322
+
2323
+ // 2. x-ad4m metadata in schema
2324
+ if (schema["x-ad4m"]?.namespace) {
2325
+ return schema["x-ad4m"].namespace;
2326
+ }
2327
+
2328
+ // 3. Infer from schema title
2329
+ if (schema.title) {
2330
+ return `${schema.title.toLowerCase()}://`;
2331
+ }
2332
+
2333
+ // 4. Try to extract from $id if it's a URL
2334
+ if (schema.$id) {
2335
+ try {
2336
+ const url = new URL(schema.$id);
2337
+ const pathParts = url.pathname.split('/').filter(p => p);
2338
+ if (pathParts.length > 0) {
2339
+ const lastPart = pathParts[pathParts.length - 1];
2340
+ const baseName = lastPart.replace(/\.schema\.json$/, '').replace(/\.json$/, '');
2341
+ return `${baseName.toLowerCase()}://`;
2342
+ }
2343
+ } catch {
2344
+ // If $id is not a valid URL, continue to error
2345
+ }
2346
+ }
2347
+
2348
+ // 5. Error if no namespace can be determined
2349
+ throw new Error(
2350
+ `Cannot infer namespace for JSON Schema. Please provide one of:
2351
+ - options.namespace
2352
+ - schema["x-ad4m"].namespace
2353
+ - schema.title
2354
+ - valid schema.$id`
2355
+ );
2356
+ }
2357
+
2358
+ /**
2359
+ * Determines the predicate for a specific property using cascading precedence
2360
+ */
2361
+ private static determinePredicate(
2362
+ schema: JSONSchema,
2363
+ propertyName: string,
2364
+ propertySchema: JSONSchemaProperty,
2365
+ namespace: string,
2366
+ options: JSONSchemaToModelOptions
2367
+ ): string {
2368
+ // 1. Explicit property mapping (highest precedence)
2369
+ if (options.propertyMapping?.[propertyName]) {
2370
+ return options.propertyMapping[propertyName];
2371
+ }
2372
+
2373
+ // 2. x-ad4m metadata in property schema
2374
+ if (propertySchema["x-ad4m"]?.through) {
2375
+ return propertySchema["x-ad4m"].through;
2376
+ }
2377
+
2378
+ // 3. Generate from namespace + property name
2379
+ if (options.predicateTemplate) {
2380
+ const normalizedNs = normalizeNamespaceString(namespace);
2381
+ const [scheme, rest] = normalizedNs.includes('://') ? normalizedNs.split('://') : ['', normalizedNs];
2382
+ const nsNoScheme = rest || '';
2383
+ return options.predicateTemplate
2384
+ .replace('${namespace}', nsNoScheme)
2385
+ .replace('${scheme}', scheme)
2386
+ .replace('${ns}', nsNoScheme)
2387
+ .replace('${title}', schema.title || '')
2388
+ .replace('${property}', propertyName);
2389
+ }
2390
+
2391
+ // 4. Custom predicate generator
2392
+ if (options.predicateGenerator) {
2393
+ return options.predicateGenerator(schema.title || '', propertyName);
2394
+ }
2395
+
2396
+ // 5. Default: namespace + property name
2397
+ const normalizedNs = normalizeNamespaceString(namespace);
2398
+ if (normalizedNs.includes('://')) {
2399
+ // For namespaces like "product://", append property directly
2400
+ return `${normalizedNs}${propertyName}`;
2401
+ } else {
2402
+ return `${normalizedNs}://${propertyName}`;
2403
+ }
2404
+ }
2405
+
2406
+ /**
2407
+ * Gets property-specific options using cascading precedence
2408
+ */
2409
+ private static getPropertyOption(
2410
+ propertyName: string,
2411
+ propertySchema: JSONSchemaProperty,
2412
+ options: JSONSchemaToModelOptions,
2413
+ optionName: keyof PropertyOptions,
2414
+ defaultValue?: any
2415
+ ): any {
2416
+ // 1. Property-specific options
2417
+ if (options.propertyOptions?.[propertyName]?.[optionName] !== undefined) {
2418
+ return options.propertyOptions[propertyName][optionName];
2419
+ }
2420
+
2421
+ // 2. x-ad4m metadata in property
2422
+ if (propertySchema["x-ad4m"]?.[optionName as keyof JSONSchemaProperty["x-ad4m"]] !== undefined) {
2423
+ return propertySchema["x-ad4m"][optionName as keyof JSONSchemaProperty["x-ad4m"]];
2424
+ }
2425
+
2426
+ // 3. Global option
2427
+ if (options[optionName as keyof JSONSchemaToModelOptions] !== undefined) {
2428
+ return options[optionName as keyof JSONSchemaToModelOptions];
2429
+ }
2430
+
2431
+ // 4. Default value
2432
+ return defaultValue;
2433
+ }
2434
+
2435
+ /**
2436
+ * Gets default value for a JSON Schema type
2437
+ */
2438
+ private static getDefaultValueForType(type?: string): any {
2439
+ switch (type) {
2440
+ case 'string': return '';
2441
+ case 'number': return 0;
2442
+ case 'integer': return 0;
2443
+ case 'boolean': return false;
2444
+ case 'array': return [];
2445
+ case 'object': return {};
2446
+ default: return '';
2447
+ }
2448
+ }
902
2449
  }
903
2450
 
904
2451
  /** Query builder for Ad4mModel queries.
@@ -927,6 +2474,7 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
927
2474
  private modelClassName: string | null = null;
928
2475
  private ctor: typeof Ad4mModel;
929
2476
  private currentSubscription?: any;
2477
+ private useSurrealDBFlag: boolean = true;
930
2478
 
931
2479
  constructor(perspective: PerspectiveProxy, ctor: typeof Ad4mModel, query?: Query) {
932
2480
  this.perspective = perspective;
@@ -1075,6 +2623,36 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
1075
2623
  return this;
1076
2624
  }
1077
2625
 
2626
+ /**
2627
+ * Enables or disables SurrealDB query path.
2628
+ *
2629
+ * @param enabled - Whether to use SurrealDB (default: true, 10-100x faster) or Prolog (legacy)
2630
+ * @returns The query builder for chaining
2631
+ *
2632
+ * @example
2633
+ * ```typescript
2634
+ * // Use SurrealDB (default)
2635
+ * const recipes = await Recipe.query(perspective)
2636
+ * .where({ category: "Dessert" })
2637
+ * .useSurrealDB(true)
2638
+ * .get();
2639
+ *
2640
+ * // Use Prolog (legacy)
2641
+ * const recipesProlog = await Recipe.query(perspective)
2642
+ * .where({ category: "Dessert" })
2643
+ * .useSurrealDB(false)
2644
+ * .get();
2645
+ * ```
2646
+ *
2647
+ * @remarks
2648
+ * Note: Subscriptions (subscribe(), countSubscribe(), paginateSubscribe()) default to SurrealDB live queries
2649
+ * if useSurrealDB(true) is set (default).
2650
+ */
2651
+ useSurrealDB(enabled: boolean = true): ModelQueryBuilder<T> {
2652
+ this.useSurrealDBFlag = enabled;
2653
+ return this;
2654
+ }
2655
+
1078
2656
  /**
1079
2657
  * Executes the query once and returns the results.
1080
2658
  *
@@ -1088,58 +2666,93 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
1088
2666
  * ```
1089
2667
  */
1090
2668
  async get(): Promise<T[]> {
1091
- const query = await this.ctor.queryToProlog(this.perspective, this.queryParams);
1092
- const result = await this.perspective.infer(query);
1093
- const { results } = await this.ctor.instancesFromPrologResult(this.perspective, this.queryParams, result);
1094
- return results as T[];
2669
+ if (this.useSurrealDBFlag) {
2670
+ const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
2671
+ const result = await this.perspective.querySurrealDB(surrealQuery);
2672
+ const { results } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
2673
+ return results as T[];
2674
+ } else {
2675
+ const query = await this.ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
2676
+ const result = await this.perspective.infer(query);
2677
+ const { results } = await this.ctor.instancesFromPrologResult(this.perspective, this.queryParams, result);
2678
+ return results as T[];
2679
+ }
1095
2680
  }
1096
2681
 
1097
2682
  /**
1098
2683
  * Subscribes to the query and receives updates when results change.
1099
- *
2684
+ *
1100
2685
  * This method:
1101
- * 1. Creates and initializes a Prolog query subscription
2686
+ * 1. Creates and initializes a SurrealDB live query subscription (default)
1102
2687
  * 2. Sets up the callback to process future updates
1103
2688
  * 3. Returns the initial results immediately
1104
- *
2689
+ *
1105
2690
  * Remember to call dispose() when you're done with the subscription
1106
2691
  * to clean up resources.
1107
- *
2692
+ *
1108
2693
  * @param callback - Function to call with updated results
1109
2694
  * @returns Initial results array
1110
- *
2695
+ *
1111
2696
  * @example
1112
2697
  * ```typescript
1113
2698
  * const builder = Recipe.query(perspective)
1114
2699
  * .where({ status: "cooking" });
1115
- *
2700
+ *
1116
2701
  * const initialRecipes = await builder.subscribe(recipes => {
1117
2702
  * console.log("Updated recipes:", recipes);
1118
2703
  * });
1119
- *
2704
+ *
1120
2705
  * // When done with subscription:
1121
2706
  * builder.dispose();
1122
2707
  * ```
2708
+ *
2709
+ * @remarks
2710
+ * By default, this uses SurrealDB live queries for real-time updates.
2711
+ * Prolog subscriptions remain available via `.useSurrealDB(false)`.
1123
2712
  */
1124
2713
  async subscribe(callback: (results: T[]) => void): Promise<T[]> {
1125
2714
  // Clean up any existing subscription
1126
2715
  this.dispose();
1127
2716
 
1128
- const query = await this.ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
1129
- this.currentSubscription = await this.perspective.subscribeInfer(query);
1130
-
1131
- const processResults = async (result: AllInstancesResult) => {
1132
- const { results } = await this.ctor.instancesFromPrologResult(this.perspective, this.queryParams, result);
1133
- callback(results as T[]);
1134
- };
1135
-
1136
- this.currentSubscription.onResult(processResults);
1137
- const { results } = await this.ctor.instancesFromPrologResult(
1138
- this.perspective,
1139
- this.queryParams,
1140
- this.currentSubscription.result
1141
- );
1142
- return results as T[];
2717
+ if (this.useSurrealDBFlag) {
2718
+ const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
2719
+ this.currentSubscription = await this.perspective.subscribeSurrealDB(surrealQuery);
2720
+
2721
+ const processResults = async (result: any) => {
2722
+ // The result from live query subscription update (handled in PerspectiveInstance listener)
2723
+ // is the new full set of results (because we re-query in Rust).
2724
+ // So we just need to map it to instances.
2725
+ const { results } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
2726
+ callback(results as T[]);
2727
+ };
2728
+
2729
+ this.currentSubscription.onResult(processResults);
2730
+
2731
+ // Process initial result
2732
+ const { results } = await this.ctor.instancesFromSurrealResult(
2733
+ this.perspective,
2734
+ this.queryParams,
2735
+ this.currentSubscription.result
2736
+ );
2737
+ return results as T[];
2738
+ } else {
2739
+ // Note: Subscriptions currently only work with Prolog
2740
+ const query = await this.ctor.queryToProlog(this.perspective, this.queryParams, this.modelClassName);
2741
+ this.currentSubscription = await this.perspective.subscribeInfer(query);
2742
+
2743
+ const processResults = async (result: AllInstancesResult) => {
2744
+ const { results } = await this.ctor.instancesFromPrologResult(this.perspective, this.queryParams, result);
2745
+ callback(results as T[]);
2746
+ };
2747
+
2748
+ this.currentSubscription.onResult(processResults);
2749
+ const { results } = await this.ctor.instancesFromPrologResult(
2750
+ this.perspective,
2751
+ this.queryParams,
2752
+ this.currentSubscription.result
2753
+ );
2754
+ return results as T[];
2755
+ }
1143
2756
  }
1144
2757
 
1145
2758
  /**
@@ -1155,52 +2768,84 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
1155
2768
  * ```
1156
2769
  */
1157
2770
  async count(): Promise<number> {
1158
- const query = await this.ctor.countQueryToProlog(this.perspective, this.queryParams, this.modelClassName);
1159
- const result = await this.perspective.infer(query);
1160
- return result?.[0]?.TotalCount || 0;
2771
+ if (this.useSurrealDBFlag) {
2772
+ const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
2773
+ const result = await this.perspective.querySurrealDB(surrealQuery);
2774
+ // Use instancesFromSurrealResult to apply JS-level filtering for advanced where conditions
2775
+ // (e.g., gt, gte, lt, lte, between, contains on properties and author/timestamp)
2776
+ // This ensures count() returns the same number as get().length
2777
+ const { totalCount } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
2778
+ return totalCount;
2779
+ } else {
2780
+ const query = await this.ctor.countQueryToProlog(this.perspective, this.queryParams, this.modelClassName);
2781
+ const result = await this.perspective.infer(query);
2782
+ return result?.[0]?.TotalCount || 0;
2783
+ }
1161
2784
  }
1162
2785
 
1163
2786
  /**
1164
2787
  * Subscribes to count updates for matching entities.
1165
- *
2788
+ *
1166
2789
  * This method:
1167
- * 1. Creates and initializes a Prolog query subscription for the count
2790
+ * 1. Creates and initializes a SurrealDB live query subscription for the count (default)
1168
2791
  * 2. Sets up the callback to process future count updates
1169
2792
  * 3. Returns the initial count immediately
1170
- *
2793
+ *
1171
2794
  * Remember to call dispose() when you're done with the subscription
1172
2795
  * to clean up resources.
1173
- *
2796
+ *
1174
2797
  * @param callback - Function to call with updated count
1175
2798
  * @returns Initial count
1176
- *
2799
+ *
1177
2800
  * @example
1178
2801
  * ```typescript
1179
2802
  * const builder = Recipe.query(perspective)
1180
2803
  * .where({ status: "active" });
1181
- *
2804
+ *
1182
2805
  * const initialCount = await builder.countSubscribe(count => {
1183
2806
  * console.log("Active items:", count);
1184
2807
  * });
1185
- *
2808
+ *
1186
2809
  * // When done with subscription:
1187
2810
  * builder.dispose();
1188
2811
  * ```
2812
+ *
2813
+ * @remarks
2814
+ * By default, this uses SurrealDB live queries for real-time updates.
2815
+ * Prolog subscriptions remain available via `.useSurrealDB(false)`.
1189
2816
  */
1190
2817
  async countSubscribe(callback: (count: number) => void): Promise<number> {
1191
2818
  // Clean up any existing subscription
1192
2819
  this.dispose();
1193
2820
 
1194
- const query = await this.ctor.countQueryToProlog(this.perspective, this.queryParams, this.modelClassName);
1195
- this.currentSubscription = await this.perspective.subscribeInfer(query);
2821
+ if (this.useSurrealDBFlag) {
2822
+ const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, this.queryParams);
2823
+ this.currentSubscription = await this.perspective.subscribeSurrealDB(surrealQuery);
1196
2824
 
1197
- const processResults = async (result: any) => {
1198
- const newCount = result?.[0]?.TotalCount || 0;
1199
- callback(newCount);
1200
- };
2825
+ const processResults = async (result: any) => {
2826
+ const { totalCount } = await this.ctor.instancesFromSurrealResult(this.perspective, this.queryParams, result);
2827
+ callback(totalCount);
2828
+ };
1201
2829
 
1202
- this.currentSubscription.onResult(processResults);
1203
- return this.currentSubscription.result?.[0]?.TotalCount || 0;
2830
+ this.currentSubscription.onResult(processResults);
2831
+ const { totalCount } = await this.ctor.instancesFromSurrealResult(
2832
+ this.perspective,
2833
+ this.queryParams,
2834
+ this.currentSubscription.result
2835
+ );
2836
+ return totalCount;
2837
+ } else {
2838
+ const query = await this.ctor.countQueryToProlog(this.perspective, this.queryParams, this.modelClassName);
2839
+ this.currentSubscription = await this.perspective.subscribeInfer(query);
2840
+
2841
+ const processResults = async (result: any) => {
2842
+ const newCount = result?.[0]?.TotalCount || 0;
2843
+ callback(newCount);
2844
+ };
2845
+
2846
+ this.currentSubscription.onResult(processResults);
2847
+ return this.currentSubscription.result?.[0]?.TotalCount || 0;
2848
+ }
1204
2849
  }
1205
2850
 
1206
2851
  /**
@@ -1220,40 +2865,51 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
1220
2865
  */
1221
2866
  async paginate(pageSize: number, pageNumber: number): Promise<PaginationResult<T>> {
1222
2867
  const paginationQuery = { ...(this.queryParams || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
1223
- const prologQuery = await this.ctor.queryToProlog(this.perspective, paginationQuery, this.modelClassName);
1224
- const result = await this.perspective.infer(prologQuery);
1225
- const { results, totalCount } = (await this.ctor.instancesFromPrologResult(this.perspective, paginationQuery, result)) as ResultsWithTotalCount<T>;
1226
- return { results, totalCount, pageSize, pageNumber };
2868
+ if (this.useSurrealDBFlag) {
2869
+ const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, paginationQuery);
2870
+ const result = await this.perspective.querySurrealDB(surrealQuery);
2871
+ const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, result)) as ResultsWithTotalCount<T>;
2872
+ return { results, totalCount, pageSize, pageNumber };
2873
+ } else {
2874
+ const prologQuery = await this.ctor.queryToProlog(this.perspective, paginationQuery, this.modelClassName);
2875
+ const result = await this.perspective.infer(prologQuery);
2876
+ const { results, totalCount } = (await this.ctor.instancesFromPrologResult(this.perspective, paginationQuery, result)) as ResultsWithTotalCount<T>;
2877
+ return { results, totalCount, pageSize, pageNumber };
2878
+ }
1227
2879
  }
1228
2880
 
1229
2881
  /**
1230
2882
  * Subscribes to paginated results updates.
1231
- *
2883
+ *
1232
2884
  * This method:
1233
- * 1. Creates and initializes a Prolog query subscription for the paginated results
2885
+ * 1. Creates and initializes a SurrealDB live query subscription for the paginated results (default)
1234
2886
  * 2. Sets up the callback to process future page updates
1235
2887
  * 3. Returns the initial page immediately
1236
- *
2888
+ *
1237
2889
  * Remember to call dispose() when you're done with the subscription
1238
2890
  * to clean up resources.
1239
- *
2891
+ *
1240
2892
  * @param pageSize - Number of items per page
1241
2893
  * @param pageNumber - Which page to retrieve (1-based)
1242
2894
  * @param callback - Function to call with updated pagination results
1243
2895
  * @returns Initial pagination results
1244
- *
2896
+ *
1245
2897
  * @example
1246
2898
  * ```typescript
1247
2899
  * const builder = Recipe.query(perspective)
1248
2900
  * .where({ category: "Main" });
1249
- *
2901
+ *
1250
2902
  * const initialPage = await builder.paginateSubscribe(10, 1, page => {
1251
2903
  * console.log("Updated page:", page.results);
1252
2904
  * });
1253
- *
2905
+ *
1254
2906
  * // When done with subscription:
1255
2907
  * builder.dispose();
1256
2908
  * ```
2909
+ *
2910
+ * @remarks
2911
+ * By default, this uses SurrealDB live queries for real-time updates.
2912
+ * Prolog subscriptions remain available via `.useSurrealDB(false)`.
1257
2913
  */
1258
2914
  async paginateSubscribe(
1259
2915
  pageSize: number,
@@ -1264,16 +2920,31 @@ export class ModelQueryBuilder<T extends Ad4mModel> {
1264
2920
  this.dispose();
1265
2921
 
1266
2922
  const paginationQuery = { ...(this.queryParams || {}), limit: pageSize, offset: pageSize * (pageNumber - 1), count: true };
1267
- const prologQuery = await this.ctor.queryToProlog(this.perspective, paginationQuery, this.modelClassName);
1268
- this.currentSubscription = await this.perspective.subscribeInfer(prologQuery);
1269
2923
 
1270
- const processResults = async (r: AllInstancesResult) => {
1271
- const { results, totalCount } = (await this.ctor.instancesFromPrologResult(this.perspective, this.queryParams, r)) as ResultsWithTotalCount<T>;
1272
- callback({ results, totalCount, pageSize, pageNumber });
1273
- };
1274
-
1275
- this.currentSubscription.onResult(processResults);
1276
- const { results, totalCount } = (await this.ctor.instancesFromPrologResult(this.perspective, paginationQuery, this.currentSubscription.result)) as ResultsWithTotalCount<T>;
1277
- return { results, totalCount, pageSize, pageNumber };
2924
+ if (this.useSurrealDBFlag) {
2925
+ const surrealQuery = await this.ctor.queryToSurrealQL(this.perspective, paginationQuery);
2926
+ this.currentSubscription = await this.perspective.subscribeSurrealDB(surrealQuery);
2927
+
2928
+ const processResults = async (result: any) => {
2929
+ const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, result)) as ResultsWithTotalCount<T>;
2930
+ callback({ results, totalCount, pageSize, pageNumber });
2931
+ };
2932
+
2933
+ this.currentSubscription.onResult(processResults);
2934
+ const { results, totalCount } = (await this.ctor.instancesFromSurrealResult(this.perspective, paginationQuery, this.currentSubscription.result)) as ResultsWithTotalCount<T>;
2935
+ return { results, totalCount, pageSize, pageNumber };
2936
+ } else {
2937
+ const prologQuery = await this.ctor.queryToProlog(this.perspective, paginationQuery, this.modelClassName);
2938
+ this.currentSubscription = await this.perspective.subscribeInfer(prologQuery);
2939
+
2940
+ const processResults = async (r: AllInstancesResult) => {
2941
+ const { results, totalCount } = (await this.ctor.instancesFromPrologResult(this.perspective, this.queryParams, r)) as ResultsWithTotalCount<T>;
2942
+ callback({ results, totalCount, pageSize, pageNumber });
2943
+ };
2944
+
2945
+ this.currentSubscription.onResult(processResults);
2946
+ const { results, totalCount } = (await this.ctor.instancesFromPrologResult(this.perspective, paginationQuery, this.currentSubscription.result)) as ResultsWithTotalCount<T>;
2947
+ return { results, totalCount, pageSize, pageNumber };
2948
+ }
1278
2949
  }
1279
2950
  }