@coasys/ad4m 0.12.0-rc1-dev.4 → 0.12.0-rc2

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 (166) hide show
  1. package/lib/index.cjs +5052 -4446
  2. package/lib/index.js +5019 -4442
  3. package/lib/src/agent/AgentClient.d.ts +4 -0
  4. package/lib/src/agent/AgentClient.js +34 -0
  5. package/lib/src/index.d.ts +2 -3
  6. package/lib/src/index.js +2 -3
  7. package/lib/src/model/Ad4mModel.d.ts +8 -782
  8. package/lib/src/model/Ad4mModel.js +160 -2354
  9. package/lib/src/model/ModelQueryBuilder.d.ts +370 -0
  10. package/lib/src/model/ModelQueryBuilder.js +556 -0
  11. package/lib/src/model/decorators.d.ts +71 -23
  12. package/lib/src/model/decorators.js +133 -384
  13. package/lib/src/model/hydration.d.ts +102 -0
  14. package/lib/src/model/hydration.js +709 -0
  15. package/lib/src/model/index.d.ts +20 -0
  16. package/lib/src/model/index.js +20 -0
  17. package/lib/src/model/{schema/fromJSONSchema.d.ts → json-schema.d.ts} +45 -12
  18. package/lib/src/model/json-schema.js +326 -0
  19. package/lib/src/model/prolog-facts.d.ts +37 -0
  20. package/lib/src/model/{prolog/generatePrologFacts.js → prolog-facts.js} +47 -52
  21. package/lib/src/model/query-common.d.ts +14 -0
  22. package/lib/src/model/query-common.js +36 -0
  23. package/lib/src/model/query-prolog.d.ts +15 -0
  24. package/lib/src/model/query-prolog.js +140 -0
  25. package/lib/src/model/query-surreal.d.ts +44 -0
  26. package/lib/src/model/query-surreal.js +249 -0
  27. package/lib/src/model/relation-filtering.test.js +838 -0
  28. package/lib/src/model/sdna.d.ts +14 -0
  29. package/lib/src/model/sdna.js +141 -0
  30. package/lib/src/model/shacl-gen.d.ts +31 -0
  31. package/lib/src/model/shacl-gen.js +246 -0
  32. package/lib/src/model/surreal-utils.d.ts +42 -0
  33. package/lib/src/model/surreal-utils.js +128 -0
  34. package/lib/src/model/types.d.ts +75 -96
  35. package/lib/src/model/types.js +4 -4
  36. package/lib/src/model/util.d.ts +4 -5
  37. package/lib/src/model/util.js +12 -32
  38. package/lib/src/perspectives/PerspectiveClient.d.ts +1 -1
  39. package/lib/src/perspectives/PerspectiveProxy.d.ts +1 -1
  40. package/lib/src/perspectives/WakerSubscriptionManager.d.ts +79 -0
  41. package/lib/src/perspectives/WakerSubscriptionManager.js +196 -0
  42. package/lib/src/runtime/RuntimeResolver.d.ts +14 -0
  43. package/lib/src/runtime/RuntimeResolver.js +73 -0
  44. package/lib/src/schema.gql +14 -0
  45. package/lib/src/shacl/SHACLShape.d.ts +23 -0
  46. package/lib/src/shacl/SHACLShape.js +45 -0
  47. package/lib/src/typeDefs.js +14 -0
  48. package/package.json +13 -8
  49. package/src/agent/AgentClient.ts +45 -0
  50. package/src/index.ts +2 -3
  51. package/src/model/Ad4mModel.ts +1089 -3686
  52. package/src/model/ModelQueryBuilder.ts +617 -0
  53. package/src/model/Subject.ts +1 -1
  54. package/src/model/decorators.ts +218 -453
  55. package/src/model/hydration.ts +796 -0
  56. package/src/model/index.ts +21 -0
  57. package/src/model/json-schema.ts +424 -0
  58. package/src/model/prolog-facts.ts +145 -0
  59. package/src/model/query-common.ts +48 -0
  60. package/src/model/query-prolog.ts +148 -0
  61. package/src/model/query-surreal.ts +280 -0
  62. package/src/model/relation-filtering.test.ts +803 -0
  63. package/src/model/sdna.ts +170 -0
  64. package/src/model/shacl-gen.ts +292 -0
  65. package/src/model/surreal-utils.ts +147 -0
  66. package/src/model/types.ts +182 -0
  67. package/src/model/util.ts +13 -36
  68. package/src/perspectives/PerspectiveClient.ts +1 -1
  69. package/src/perspectives/PerspectiveProxy.ts +1 -1
  70. package/src/perspectives/WakerSubscriptionManager.ts +292 -0
  71. package/src/runtime/RuntimeResolver.ts +53 -0
  72. package/src/shacl/SHACLShape.ts +83 -0
  73. package/lib/src/Ad4mClient.test.js +0 -1204
  74. package/lib/src/Literal.test.d.ts +0 -1
  75. package/lib/src/Literal.test.js +0 -41
  76. package/lib/src/model/mutation.d.ts +0 -81
  77. package/lib/src/model/mutation.js +0 -317
  78. package/lib/src/model/parentUtils.d.ts +0 -32
  79. package/lib/src/model/parentUtils.js +0 -64
  80. package/lib/src/model/prolog/generatePrologFacts.d.ts +0 -36
  81. package/lib/src/model/prolog/index.d.ts +0 -1
  82. package/lib/src/model/prolog/index.js +0 -1
  83. package/lib/src/model/query/ModelQueryBuilder.d.ts +0 -82
  84. package/lib/src/model/query/ModelQueryBuilder.js +0 -115
  85. package/lib/src/model/query/QueryBuilder.d.ts +0 -101
  86. package/lib/src/model/query/QueryBuilder.js +0 -193
  87. package/lib/src/model/query/SurrealQueryBuilder.d.ts +0 -48
  88. package/lib/src/model/query/SurrealQueryBuilder.js +0 -371
  89. package/lib/src/model/query/fetchInstance.d.ts +0 -24
  90. package/lib/src/model/query/fetchInstance.js +0 -144
  91. package/lib/src/model/query/hydration.d.ts +0 -54
  92. package/lib/src/model/query/hydration.js +0 -214
  93. package/lib/src/model/query/operations.d.ts +0 -59
  94. package/lib/src/model/query/operations.js +0 -384
  95. package/lib/src/model/query/snapshot.d.ts +0 -59
  96. package/lib/src/model/query/snapshot.js +0 -106
  97. package/lib/src/model/query/surrealCompiler.d.ts +0 -42
  98. package/lib/src/model/query/surrealCompiler.js +0 -304
  99. package/lib/src/model/schema/fromJSONSchema.js +0 -264
  100. package/lib/src/model/schema/metadata.d.ts +0 -15
  101. package/lib/src/model/schema/metadata.js +0 -112
  102. package/lib/src/model/subscription.d.ts +0 -47
  103. package/lib/src/model/subscription.js +0 -231
  104. package/lib/src/model/transaction.d.ts +0 -27
  105. package/lib/src/model/transaction.js +0 -32
  106. package/lib/src/shims/reflect-metadata.d.ts +0 -0
  107. package/lib/src/shims/type-graphql.d.ts +0 -32
  108. package/lib/src/src/Ad4mClient.d.ts +0 -28
  109. package/lib/src/src/Address.d.ts +0 -1
  110. package/lib/src/src/DID.d.ts +0 -1
  111. package/lib/src/src/Exception.d.ts +0 -7
  112. package/lib/src/src/Literal.d.ts +0 -7
  113. package/lib/src/src/PubSub.d.ts +0 -17
  114. package/lib/src/src/SmartLiteral.d.ts +0 -12
  115. package/lib/src/src/agent/Agent.d.ts +0 -110
  116. package/lib/src/src/agent/AgentClient.d.ts +0 -62
  117. package/lib/src/src/agent/AgentResolver.d.ts +0 -30
  118. package/lib/src/src/agent/AgentStatus.d.ts +0 -8
  119. package/lib/src/src/ai/AIClient.d.ts +0 -32
  120. package/lib/src/src/ai/AIResolver.d.ts +0 -75
  121. package/lib/src/src/ai/Tasks.d.ts +0 -37
  122. package/lib/src/src/buildSchema.d.ts +0 -1
  123. package/lib/src/src/expression/Expression.d.ts +0 -28
  124. package/lib/src/src/expression/ExpressionClient.d.ts +0 -13
  125. package/lib/src/src/expression/ExpressionRef.d.ts +0 -9
  126. package/lib/src/src/expression/ExpressionResolver.d.ts +0 -10
  127. package/lib/src/src/index.d.ts +0 -35
  128. package/lib/src/src/jestSetup.d.ts +0 -1
  129. package/lib/src/src/language/Icon.d.ts +0 -4
  130. package/lib/src/src/language/Language.d.ts +0 -206
  131. package/lib/src/src/language/LanguageClient.d.ts +0 -17
  132. package/lib/src/src/language/LanguageContext.d.ts +0 -37
  133. package/lib/src/src/language/LanguageHandle.d.ts +0 -9
  134. package/lib/src/src/language/LanguageMeta.d.ts +0 -35
  135. package/lib/src/src/language/LanguageRef.d.ts +0 -6
  136. package/lib/src/src/language/LanguageResolver.d.ts +0 -19
  137. package/lib/src/src/links/Links.d.ts +0 -39
  138. package/lib/src/src/links/Links.test.d.ts +0 -1
  139. package/lib/src/src/model/Ad4mModel.d.ts +0 -1438
  140. package/lib/src/src/model/Ad4mModel.test.d.ts +0 -1
  141. package/lib/src/src/model/Subject.d.ts +0 -25
  142. package/lib/src/src/model/decorators.d.ts +0 -545
  143. package/lib/src/src/model/util.d.ts +0 -12
  144. package/lib/src/src/neighbourhood/Neighbourhood.d.ts +0 -10
  145. package/lib/src/src/neighbourhood/NeighbourhoodClient.d.ts +0 -25
  146. package/lib/src/src/neighbourhood/NeighbourhoodProxy.d.ts +0 -19
  147. package/lib/src/src/neighbourhood/NeighbourhoodProxy.test.d.ts +0 -1
  148. package/lib/src/src/neighbourhood/NeighbourhoodResolver.d.ts +0 -24
  149. package/lib/src/src/perspectives/LinkQuery.d.ts +0 -11
  150. package/lib/src/src/perspectives/Perspective.d.ts +0 -38
  151. package/lib/src/src/perspectives/Perspective.test.d.ts +0 -1
  152. package/lib/src/src/perspectives/PerspectiveClient.d.ts +0 -97
  153. package/lib/src/src/perspectives/PerspectiveDiff.d.ts +0 -9
  154. package/lib/src/src/perspectives/PerspectiveHandle.d.ts +0 -18
  155. package/lib/src/src/perspectives/PerspectiveProxy.d.ts +0 -865
  156. package/lib/src/src/perspectives/PerspectiveResolver.d.ts +0 -57
  157. package/lib/src/src/runtime/RuntimeClient.d.ts +0 -56
  158. package/lib/src/src/runtime/RuntimeResolver.d.ts +0 -132
  159. package/lib/src/src/shacl/SHACLFlow.d.ts +0 -171
  160. package/lib/src/src/shacl/SHACLFlow.test.d.ts +0 -1
  161. package/lib/src/src/shacl/SHACLShape.d.ts +0 -117
  162. package/lib/src/src/shacl/SHACLShape.test.d.ts +0 -1
  163. package/lib/src/src/typeDefs.d.ts +0 -1
  164. package/lib/src/src/unwrapApolloResult.d.ts +0 -2
  165. package/lib/src/src/utils.d.ts +0 -25
  166. /package/lib/src/{Ad4mClient.test.d.ts → model/relation-filtering.test.d.ts} +0 -0
@@ -1,3 +1,5 @@
1
+ import type { Where } from "./types";
2
+ import type { ConformanceCondition } from "../shacl/SHACLShape";
1
3
  /** Metadata stored for each property via @Property / @Optional / @ReadOnly / @Flag */
2
4
  export interface PropertyMetadataEntry extends PropertyOptions {
3
5
  /** Internal computed writable flag (inverse of readOnly) for SDNA/SHACL compatibility */
@@ -21,6 +23,18 @@ export interface RelationMetadataEntry {
21
23
  * The expression can reference 'Base' which will be replaced with the instance's base expression.
22
24
  */
23
25
  getter?: string;
26
+ /**
27
+ * Whether to auto-generate a conformance filter when `target` is set.
28
+ * Defaults to `true` — set to `false` to opt out of DB-level type filtering
29
+ * while keeping hydration capability via `include`.
30
+ */
31
+ filter?: boolean;
32
+ /**
33
+ * Filter constraints on linked target nodes using the query DSL.
34
+ * Property names reference the target model's properties.
35
+ * Overrides auto-derived conformance when set.
36
+ */
37
+ where?: Where;
24
38
  }
25
39
  /**
26
40
  * Retrieve property metadata for a given class constructor.
@@ -54,23 +68,21 @@ export interface Ad4mModelLike {
54
68
  generateSHACL?: () => any;
55
69
  }
56
70
  /**
57
- * Convert a model instance to a plain serializable object.
58
- * Reads the property metadata and extracts values from the instance.
59
- */
60
- export declare function instanceToSerializable(instance: any): Record<string, any>;
61
- /**
62
- * Generate a random identifier string (lowercase alpha).
63
- * Generate a random identifier string of the given length (lowercase alpha).
71
+ * Build a conformance filter for a relation whose target model is known.
72
+ *
73
+ * Inspects the target class's property metadata to derive:
74
+ * - `conformanceConditions`: Structured, DB-agnostic conditions (flag & required checks)
75
+ * - `getter`: Pre-computed SurrealQL expression that traverses outgoing links and filters
76
+ * target nodes to only those conforming to the target shape.
77
+ *
78
+ * @param relationPredicate - The relation's predicate URI (e.g. "flux://entry_type")
79
+ * @param targetClass - The target model class (resolved from the target() thunk)
80
+ * @returns `{ getter, conformanceConditions }` or `undefined` if no conditions could be derived
64
81
  */
65
- export declare function makeRandomId(length: number): string;
66
- export declare class PerspectiveAction {
67
- action: string;
68
- source: string;
69
- predicate: string;
70
- target: string;
71
- }
72
- export declare function addLink(source: string, predicate: string, target: string): PerspectiveAction;
73
- export declare function hasLink(predicate: string): string;
82
+ export declare function buildConformanceFilter(relationPredicate: string, targetClass: Ad4mModelLike): {
83
+ getter: string;
84
+ conformanceConditions: ConformanceCondition[];
85
+ } | undefined;
74
86
  export interface PropertyOptions {
75
87
  /**
76
88
  * The predicate of the property. All properties must have this option.
@@ -388,18 +400,54 @@ export declare function ReadOnly(opts: PropertyOptions): <T>(target: T, key: key
388
400
  * Options for relation decorators (@HasMany, @HasOne, @BelongsToOne, @BelongsToMany).
389
401
  */
390
402
  export interface RelationOptions {
391
- /** The predicate URI used to link the two models */
392
- through: string;
393
- /** The target model class (use a thunk to avoid circular-dependency issues). Optional for untyped string relations. */
403
+ /**
404
+ * The predicate URI used to link the two models.
405
+ * Defaults to `'ad4m://has_child'` when omitted.
406
+ * Cannot be combined with `getter`.
407
+ */
408
+ through?: string;
409
+ /** The target model class (use a thunk to avoid circular-dependency issues). Optional for untyped string relations.
410
+ * Cannot be combined with `getter`. */
394
411
  target?: () => Ad4mModelLike;
395
412
  /**
396
413
  * Custom SurrealQL getter to resolve the relation values. Use this for custom graph traversals.
397
414
  * The expression can reference 'Base' which will be replaced with the instance's base expression.
398
415
  * Example: "(<-link[WHERE predicate = 'flux://has_reply'].out.uri)"
416
+ *
417
+ * Mutually exclusive with `through` and `target`. When `getter` is provided the
418
+ * relation is read-only (no adder/remover actions are generated).
399
419
  */
400
420
  getter?: string;
401
421
  /** Whether the link is stored locally (not shared on the network) */
402
422
  local?: boolean;
423
+ /**
424
+ * Whether to auto-generate a DB-level conformance filter when `target` is set.
425
+ * Defaults to `true` when `target` is present — the query will only return linked
426
+ * nodes whose shape matches the target model (required properties, flags, etc.).
427
+ * Set to `false` to opt out of filtering while keeping hydration capability.
428
+ */
429
+ filter?: boolean;
430
+ /**
431
+ * Filter constraints on the linked target nodes, using the same query DSL
432
+ * as `Model.query().where(...)`. Property names reference the **target**
433
+ * model's properties (resolved via target metadata).
434
+ *
435
+ * When `target` is set and `where` is omitted, conformance conditions are
436
+ * auto-derived from the target shape (flags + required properties).
437
+ * Providing `where` overrides this auto-derivation.
438
+ *
439
+ * Mutually exclusive with `getter` and `filter: false`.
440
+ *
441
+ * @example
442
+ * ```typescript
443
+ * @HasMany(() => Message, {
444
+ * through: "flux://entry_type",
445
+ * where: { status: "active", priority: { gte: 3 } }
446
+ * })
447
+ * activeMessages: Message[] = []
448
+ * ```
449
+ */
450
+ where?: Where;
403
451
  }
404
452
  /**
405
453
  * Utility type that describes the auto-generated helper methods for a HasMany
@@ -453,7 +501,7 @@ export type HasManyMethods<Keys extends string> = {
453
501
  * ```
454
502
  */
455
503
  export declare function HasMany(opts: RelationOptions): PropertyDecorator;
456
- export declare function HasMany(target: () => Ad4mModelLike, opts: Omit<RelationOptions, 'target'>): PropertyDecorator;
504
+ export declare function HasMany(target: () => Ad4mModelLike, opts?: Omit<RelationOptions, 'target'>): PropertyDecorator;
457
505
  /**
458
506
  * Decorator for defining a one-to-one relation (owning side).
459
507
  *
@@ -479,7 +527,7 @@ export declare function HasMany(target: () => Ad4mModelLike, opts: Omit<Relation
479
527
  * ```
480
528
  */
481
529
  export declare function HasOne(opts: RelationOptions): PropertyDecorator;
482
- export declare function HasOne(target: () => Ad4mModelLike, opts: Omit<RelationOptions, 'target'>): PropertyDecorator;
530
+ export declare function HasOne(target: () => Ad4mModelLike, opts?: Omit<RelationOptions, 'target'>): PropertyDecorator;
483
531
  /**
484
532
  * Decorator for defining the inverse side of a one-to-one relation.
485
533
  *
@@ -505,7 +553,7 @@ export declare function HasOne(target: () => Ad4mModelLike, opts: Omit<RelationO
505
553
  * ```
506
554
  */
507
555
  export declare function BelongsToOne(opts: RelationOptions): PropertyDecorator;
508
- export declare function BelongsToOne(target: () => Ad4mModelLike, opts: Omit<RelationOptions, 'target'>): PropertyDecorator;
556
+ export declare function BelongsToOne(target: () => Ad4mModelLike, opts?: Omit<RelationOptions, 'target'>): PropertyDecorator;
509
557
  /**
510
558
  * Decorator for defining the inverse side of a many-to-many relation.
511
559
  *
@@ -531,4 +579,4 @@ export declare function BelongsToOne(target: () => Ad4mModelLike, opts: Omit<Rel
531
579
  * ```
532
580
  */
533
581
  export declare function BelongsToMany(opts: RelationOptions): PropertyDecorator;
534
- export declare function BelongsToMany(target: () => Ad4mModelLike, opts: Omit<RelationOptions, 'target'>): PropertyDecorator;
582
+ export declare function BelongsToMany(target: () => Ad4mModelLike, opts?: Omit<RelationOptions, 'target'>): PropertyDecorator;