@nicia-ai/typegraph 0.1.1 → 0.3.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.
Files changed (150) hide show
  1. package/README.md +23 -0
  2. package/dist/{ast-BVyihVbP.d.cts → ast-CXFx6bF6.d.ts} +45 -165
  3. package/dist/{ast-BVyihVbP.d.ts → ast-D-3bOanX.d.cts} +45 -165
  4. package/dist/backend/drizzle/index.cjs +20 -21
  5. package/dist/backend/drizzle/index.d.cts +6 -5
  6. package/dist/backend/drizzle/index.d.ts +6 -5
  7. package/dist/backend/drizzle/index.js +8 -9
  8. package/dist/backend/drizzle/postgres.cjs +9 -10
  9. package/dist/backend/drizzle/postgres.d.cts +9 -11
  10. package/dist/backend/drizzle/postgres.d.ts +9 -11
  11. package/dist/backend/drizzle/postgres.js +6 -7
  12. package/dist/backend/drizzle/schema/postgres.cjs +10 -11
  13. package/dist/backend/drizzle/schema/postgres.d.cts +6 -5
  14. package/dist/backend/drizzle/schema/postgres.d.ts +6 -5
  15. package/dist/backend/drizzle/schema/postgres.js +3 -4
  16. package/dist/backend/drizzle/schema/sqlite.cjs +10 -11
  17. package/dist/backend/drizzle/schema/sqlite.d.cts +6 -5
  18. package/dist/backend/drizzle/schema/sqlite.d.ts +6 -5
  19. package/dist/backend/drizzle/schema/sqlite.js +3 -4
  20. package/dist/backend/drizzle/sqlite.cjs +9 -10
  21. package/dist/backend/drizzle/sqlite.d.cts +17 -18
  22. package/dist/backend/drizzle/sqlite.d.ts +17 -18
  23. package/dist/backend/drizzle/sqlite.js +6 -7
  24. package/dist/backend/postgres/index.cjs +21 -18
  25. package/dist/backend/postgres/index.d.cts +8 -7
  26. package/dist/backend/postgres/index.d.ts +8 -7
  27. package/dist/backend/postgres/index.js +8 -9
  28. package/dist/backend/sqlite/index.cjs +27 -22
  29. package/dist/backend/sqlite/index.cjs.map +1 -1
  30. package/dist/backend/sqlite/index.d.cts +7 -6
  31. package/dist/backend/sqlite/index.d.ts +7 -6
  32. package/dist/backend/sqlite/index.js +18 -13
  33. package/dist/backend/sqlite/index.js.map +1 -1
  34. package/dist/{chunk-YM5AL65Y.cjs → chunk-2WVFEIHR.cjs} +29 -3
  35. package/dist/chunk-2WVFEIHR.cjs.map +1 -0
  36. package/dist/{chunk-4PIEL2VO.js → chunk-3PURVEA4.js} +36 -5
  37. package/dist/chunk-3PURVEA4.js.map +1 -0
  38. package/dist/chunk-4HARSV2G.js +1448 -0
  39. package/dist/chunk-4HARSV2G.js.map +1 -0
  40. package/dist/{chunk-IIAT36MI.js → chunk-54WJF3DW.js} +29 -3
  41. package/dist/chunk-54WJF3DW.js.map +1 -0
  42. package/dist/chunk-CMHFS34N.cjs +390 -0
  43. package/dist/chunk-CMHFS34N.cjs.map +1 -0
  44. package/dist/chunk-DD6ONEBN.cjs +1264 -0
  45. package/dist/chunk-DD6ONEBN.cjs.map +1 -0
  46. package/dist/chunk-F2BZSEFE.js +388 -0
  47. package/dist/chunk-F2BZSEFE.js.map +1 -0
  48. package/dist/{chunk-DDM2FZRJ.cjs → chunk-JQDWEX6V.cjs} +24 -24
  49. package/dist/{chunk-DDM2FZRJ.cjs.map → chunk-JQDWEX6V.cjs.map} +1 -1
  50. package/dist/chunk-NP4G4ZKM.js +1228 -0
  51. package/dist/chunk-NP4G4ZKM.js.map +1 -0
  52. package/dist/{chunk-UJAGXJDG.cjs → chunk-NU2XNMVI.cjs} +38 -7
  53. package/dist/chunk-NU2XNMVI.cjs.map +1 -0
  54. package/dist/{chunk-JKTO7TW3.js → chunk-O5XPCJLF.js} +25 -3
  55. package/dist/chunk-O5XPCJLF.js.map +1 -0
  56. package/dist/{chunk-2QHQ2C4P.js → chunk-OGGLFYFA.js} +36 -5
  57. package/dist/chunk-OGGLFYFA.js.map +1 -0
  58. package/dist/{chunk-SV5H3XM5.cjs → chunk-OYL2SGBD.cjs} +26 -2
  59. package/dist/chunk-OYL2SGBD.cjs.map +1 -0
  60. package/dist/chunk-SFY2PPOY.cjs +1469 -0
  61. package/dist/chunk-SFY2PPOY.cjs.map +1 -0
  62. package/dist/{chunk-JDAET5LO.js → chunk-SMLIWLS7.js} +9 -9
  63. package/dist/chunk-SMLIWLS7.js.map +1 -0
  64. package/dist/{chunk-VXRVGFCI.js → chunk-U3452TEU.js} +17 -17
  65. package/dist/{chunk-VXRVGFCI.js.map → chunk-U3452TEU.js.map} +1 -1
  66. package/dist/{chunk-MNO33ASC.cjs → chunk-UYMT4LO2.cjs} +9 -8
  67. package/dist/chunk-UYMT4LO2.cjs.map +1 -0
  68. package/dist/chunk-V7CS2MDB.cjs +289 -0
  69. package/dist/chunk-V7CS2MDB.cjs.map +1 -0
  70. package/dist/chunk-WE5BKYNB.js +287 -0
  71. package/dist/chunk-WE5BKYNB.js.map +1 -0
  72. package/dist/{chunk-L642L24T.js → chunk-XDTYTNYL.js} +14 -21
  73. package/dist/chunk-XDTYTNYL.js.map +1 -0
  74. package/dist/{chunk-N4AOJ3VF.cjs → chunk-XZL6MCZJ.cjs} +38 -7
  75. package/dist/chunk-XZL6MCZJ.cjs.map +1 -0
  76. package/dist/{chunk-DBFCKELK.cjs → chunk-ZJHQZZT2.cjs} +18 -27
  77. package/dist/chunk-ZJHQZZT2.cjs.map +1 -0
  78. package/dist/index-Dkicw49A.d.cts +373 -0
  79. package/dist/index-Dkicw49A.d.ts +373 -0
  80. package/dist/index.cjs +5916 -3371
  81. package/dist/index.cjs.map +1 -1
  82. package/dist/index.d.cts +24 -664
  83. package/dist/index.d.ts +24 -664
  84. package/dist/index.js +5783 -3220
  85. package/dist/index.js.map +1 -1
  86. package/dist/indexes/index.cjs +16 -17
  87. package/dist/indexes/index.d.cts +5 -4
  88. package/dist/indexes/index.d.ts +5 -4
  89. package/dist/indexes/index.js +2 -3
  90. package/dist/interchange/index.cjs +9 -10
  91. package/dist/interchange/index.cjs.map +1 -1
  92. package/dist/interchange/index.d.cts +5 -3
  93. package/dist/interchange/index.d.ts +5 -3
  94. package/dist/interchange/index.js +8 -9
  95. package/dist/interchange/index.js.map +1 -1
  96. package/dist/manager-Jc5Btay9.d.cts +493 -0
  97. package/dist/manager-e9LXthrx.d.ts +493 -0
  98. package/dist/profiler/index.cjs +2 -9
  99. package/dist/profiler/index.cjs.map +1 -1
  100. package/dist/profiler/index.d.cts +9 -161
  101. package/dist/profiler/index.d.ts +9 -161
  102. package/dist/profiler/index.js +4 -5
  103. package/dist/profiler/index.js.map +1 -1
  104. package/dist/schema/index.cjs +145 -0
  105. package/dist/schema/index.cjs.map +1 -0
  106. package/dist/schema/index.d.cts +237 -0
  107. package/dist/schema/index.d.ts +237 -0
  108. package/dist/schema/index.js +72 -0
  109. package/dist/schema/index.js.map +1 -0
  110. package/dist/{store-60Lcfi0w.d.ts → store-DM3Tk3Pw.d.ts} +871 -1314
  111. package/dist/{store-Bifii8MZ.d.cts → store-nbBybLWP.d.cts} +871 -1314
  112. package/dist/{test-helpers-BjyRYJZX.d.ts → test-helpers-CIq1Hhj1.d.ts} +5 -1
  113. package/dist/{test-helpers-NoQXhleQ.d.cts → test-helpers-DPRFVky4.d.cts} +5 -1
  114. package/dist/{types-D_3mEv2y.d.ts → types-BL1GyVku.d.cts} +2 -2
  115. package/dist/{types-CjZ7g_7v.d.ts → types-Cdbi4hcx.d.ts} +292 -4
  116. package/dist/{types-BrSfFSpW.d.cts → types-DCGa53O2.d.ts} +2 -2
  117. package/dist/{types-DDOSfrih.d.cts → types-DDP0MGBF.d.cts} +292 -4
  118. package/dist/{types-a5rAxC92.d.cts → types-DHRsi6j9.d.cts} +4 -3
  119. package/dist/types-DTJEu_-h.d.cts +158 -0
  120. package/dist/types-DTJEu_-h.d.ts +158 -0
  121. package/dist/{types-CX4cLd7M.d.ts → types-ZT5mlism.d.ts} +4 -3
  122. package/package.json +17 -2
  123. package/dist/chunk-2QHQ2C4P.js.map +0 -1
  124. package/dist/chunk-3A5TKOEJ.js +0 -306
  125. package/dist/chunk-3A5TKOEJ.js.map +0 -1
  126. package/dist/chunk-4PIEL2VO.js.map +0 -1
  127. package/dist/chunk-536PH5FT.js +0 -342
  128. package/dist/chunk-536PH5FT.js.map +0 -1
  129. package/dist/chunk-DBFCKELK.cjs.map +0 -1
  130. package/dist/chunk-DGUM43GV.js +0 -10
  131. package/dist/chunk-DGUM43GV.js.map +0 -1
  132. package/dist/chunk-F32HCHYA.cjs +0 -680
  133. package/dist/chunk-F32HCHYA.cjs.map +0 -1
  134. package/dist/chunk-IIAT36MI.js.map +0 -1
  135. package/dist/chunk-JDAET5LO.js.map +0 -1
  136. package/dist/chunk-JEQ2X3Z6.cjs +0 -12
  137. package/dist/chunk-JEQ2X3Z6.cjs.map +0 -1
  138. package/dist/chunk-JKTO7TW3.js.map +0 -1
  139. package/dist/chunk-L642L24T.js.map +0 -1
  140. package/dist/chunk-MFVCSNIY.cjs +0 -308
  141. package/dist/chunk-MFVCSNIY.cjs.map +0 -1
  142. package/dist/chunk-MNO33ASC.cjs.map +0 -1
  143. package/dist/chunk-N4AOJ3VF.cjs.map +0 -1
  144. package/dist/chunk-RYT4H46I.js +0 -646
  145. package/dist/chunk-RYT4H46I.js.map +0 -1
  146. package/dist/chunk-SV5H3XM5.cjs.map +0 -1
  147. package/dist/chunk-TXHKFLWX.cjs +0 -344
  148. package/dist/chunk-TXHKFLWX.cjs.map +0 -1
  149. package/dist/chunk-UJAGXJDG.cjs.map +0 -1
  150. package/dist/chunk-YM5AL65Y.cjs.map +0 -1
package/README.md CHANGED
@@ -45,3 +45,26 @@ await store.edges.knows.create(alice, bob);
45
45
  See the repo README for more.
46
46
 
47
47
  Examples: [github.com/nicia-ai/typegraph/tree/main/packages/typegraph/examples](https://github.com/nicia-ai/typegraph/tree/main/packages/typegraph/examples)
48
+
49
+ ## Performance Smoke Check
50
+
51
+ The perf harness lives in `@nicia-ai/typegraph-benchmarks`; these commands delegate to it.
52
+
53
+ Run a deterministic SQLite perf sanity suite with guardrails:
54
+
55
+ ```bash
56
+ pnpm --filter @nicia-ai/typegraph test:perf
57
+ ```
58
+
59
+ Run the same guardrailed suite against PostgreSQL (requires `POSTGRES_URL`):
60
+
61
+ ```bash
62
+ POSTGRES_URL=postgresql://typegraph:typegraph@127.0.0.1:5432/typegraph_test \
63
+ pnpm --filter @nicia-ai/typegraph test:perf:postgres
64
+ ```
65
+
66
+ For report-only mode (no pass/fail guardrails):
67
+
68
+ ```bash
69
+ pnpm --filter @nicia-ai/typegraph bench:perf
70
+ ```
@@ -1,159 +1,4 @@
1
- import { z } from 'zod';
2
-
3
- /** Brand key for NodeType */
4
- declare const NODE_TYPE_BRAND: "__nodeType";
5
- /** Brand key for EdgeType */
6
- declare const EDGE_TYPE_BRAND: "__edgeType";
7
- /** Brand symbol for NodeId */
8
- declare const __nodeId: unique symbol;
9
- /**
10
- * A node type definition.
11
- *
12
- * Created via `defineNode()`. Represents a type of node in the graph
13
- * with an associated Zod schema for properties.
14
- */
15
- type NodeType<K extends string = string, S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> = Readonly<{
16
- [NODE_TYPE_BRAND]: true;
17
- name: K;
18
- schema: S;
19
- description: string | undefined;
20
- }>;
21
- /**
22
- * Branded node ID type.
23
- *
24
- * Prevents mixing IDs from different node types at compile time.
25
- */
26
- type NodeId<N extends NodeType> = string & Readonly<{
27
- [__nodeId]: N;
28
- }>;
29
- /**
30
- * Infer the props type from a NodeType.
31
- */
32
- type NodeProps<N extends NodeType> = z.infer<N["schema"]>;
33
- /**
34
- * An edge type definition.
35
- *
36
- * Created via `defineEdge()`. Represents a type of edge in the graph
37
- * with an optional Zod schema for properties.
38
- *
39
- * Optionally includes `from` and `to` arrays that define the allowed
40
- * source and target node types (domain and range constraints).
41
- */
42
- type EdgeType<K extends string = string, S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, From extends readonly NodeType[] | undefined = undefined, To extends readonly NodeType[] | undefined = undefined> = Readonly<{
43
- [EDGE_TYPE_BRAND]: true;
44
- name: K;
45
- schema: S;
46
- description: string | undefined;
47
- from: From;
48
- to: To;
49
- }>;
50
- /**
51
- * Base edge type for use in constraints - accepts any from/to configuration.
52
- */
53
- type AnyEdgeType = EdgeType<string, z.ZodObject<z.ZodRawShape>, readonly NodeType[] | undefined, readonly NodeType[] | undefined>;
54
- /**
55
- * An edge type that has both from and to constraints defined.
56
- * Can be used directly in defineGraph without an EdgeRegistration wrapper.
57
- */
58
- type EdgeTypeWithEndpoints = EdgeType<string, z.ZodObject<z.ZodRawShape>, readonly NodeType[], readonly NodeType[]>;
59
- /**
60
- * Infer the props type from an EdgeType.
61
- */
62
- type EdgeProps<E extends AnyEdgeType> = z.infer<E["schema"]>;
63
- /**
64
- * Delete behaviors for nodes.
65
- */
66
- type DeleteBehavior = "restrict" | "cascade" | "disconnect";
67
- /**
68
- * Edge cardinality constraints.
69
- */
70
- type Cardinality = "many" | "one" | "unique" | "oneActive";
71
- /**
72
- * Endpoint existence modes for edge validation.
73
- */
74
- type EndpointExistence = "notDeleted" | "currentlyValid" | "ever";
75
- /**
76
- * Temporal query modes.
77
- */
78
- type TemporalMode = "current" | "asOf" | "includeEnded" | "includeTombstones";
79
- /**
80
- * Uniqueness constraint scope.
81
- */
82
- type UniquenessScope = "kind" | "kindWithSubClasses";
83
- /**
84
- * Collation for uniqueness constraints.
85
- */
86
- type Collation = "binary" | "caseInsensitive";
87
- /**
88
- * Uniqueness constraint definition.
89
- */
90
- type UniqueConstraint<S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> = Readonly<{
91
- name: string;
92
- fields: readonly (keyof z.infer<S> & string)[];
93
- where?: (props: UniqueConstraintPredicateBuilder<S>) => UniqueConstraintPredicate;
94
- scope: UniquenessScope;
95
- collation: Collation;
96
- }>;
97
- /**
98
- * Predicate builder for uniqueness constraint where clause.
99
- * Uses -? to make all fields required in the builder, even if optional in the schema.
100
- */
101
- type UniqueConstraintPredicateBuilder<S extends z.ZodObject<z.ZodRawShape>> = Readonly<{
102
- [K in keyof z.infer<S>]-?: UniqueConstraintField;
103
- }>;
104
- /**
105
- * Field operations for uniqueness constraint predicates.
106
- */
107
- type UniqueConstraintField = Readonly<{
108
- isNull: () => UniqueConstraintPredicate;
109
- isNotNull: () => UniqueConstraintPredicate;
110
- }>;
111
- /**
112
- * A uniqueness constraint predicate (internal representation).
113
- */
114
- type UniqueConstraintPredicate = Readonly<{
115
- __type: "unique_predicate";
116
- field: string;
117
- op: "isNull" | "isNotNull";
118
- }>;
119
- /**
120
- * Node registration in a graph definition.
121
- */
122
- type NodeRegistration<N extends NodeType = NodeType> = Readonly<{
123
- type: N;
124
- unique?: readonly UniqueConstraint<N["schema"]>[];
125
- onDelete?: DeleteBehavior;
126
- }>;
127
- /**
128
- * Edge registration in a graph definition.
129
- */
130
- type EdgeRegistration<E extends AnyEdgeType = AnyEdgeType, FromTypes extends NodeType = NodeType, ToTypes extends NodeType = NodeType> = Readonly<{
131
- type: E;
132
- from: readonly FromTypes[];
133
- to: readonly ToTypes[];
134
- cardinality?: Cardinality;
135
- endpointExistence?: EndpointExistence;
136
- }>;
137
- /**
138
- * Default settings for a graph.
139
- */
140
- type GraphDefaults = Readonly<{
141
- onNodeDelete?: DeleteBehavior;
142
- temporalMode?: TemporalMode;
143
- }>;
144
- /**
145
- * Checks if a value is a NodeType.
146
- */
147
- declare function isNodeType(value: unknown): value is NodeType;
148
- /**
149
- * Checks if a value is an EdgeType.
150
- */
151
- declare function isEdgeType(value: unknown): value is AnyEdgeType;
152
- /**
153
- * Checks if a value is an EdgeType with both from and to constraints defined.
154
- * Such edges can be used directly in defineGraph without an EdgeRegistration wrapper.
155
- */
156
- declare function isEdgeTypeWithEndpoints(value: unknown): value is EdgeTypeWithEndpoints;
1
+ import { T as TemporalMode } from './types-DTJEu_-h.js';
157
2
 
158
3
  declare const MAX_JSON_POINTER_DEPTH: 5;
159
4
  type JsonPointer = string & {
@@ -224,6 +69,17 @@ type LiteralValue = Readonly<{
224
69
  value: string | number | boolean;
225
70
  valueType?: ValueType | undefined;
226
71
  }>;
72
+ /**
73
+ * A parameter reference for prepared queries.
74
+ *
75
+ * Used in place of a literal value to create parameterized queries
76
+ * that can be executed multiple times with different bindings.
77
+ */
78
+ type ParameterRef = Readonly<{
79
+ __type: "parameter";
80
+ name: string;
81
+ valueType?: ValueType | undefined;
82
+ }>;
227
83
  /**
228
84
  * Supported value types for predicates.
229
85
  */
@@ -243,7 +99,7 @@ type ComparisonPredicate = Readonly<{
243
99
  __type: "comparison";
244
100
  op: ComparisonOp;
245
101
  left: FieldRef;
246
- right: LiteralValue | LiteralValue[];
102
+ right: LiteralValue | LiteralValue[] | ParameterRef;
247
103
  }>;
248
104
  /**
249
105
  * A string predicate.
@@ -252,7 +108,7 @@ type StringPredicate = Readonly<{
252
108
  __type: "string_op";
253
109
  op: StringOp;
254
110
  field: FieldRef;
255
- pattern: string;
111
+ pattern: string | ParameterRef;
256
112
  }>;
257
113
  /**
258
114
  * A null check predicate.
@@ -268,8 +124,8 @@ type NullPredicate = Readonly<{
268
124
  type BetweenPredicate = Readonly<{
269
125
  __type: "between";
270
126
  field: FieldRef;
271
- lower: LiteralValue;
272
- upper: LiteralValue;
127
+ lower: LiteralValue | ParameterRef;
128
+ upper: LiteralValue | ParameterRef;
273
129
  }>;
274
130
  /**
275
131
  * Array operators.
@@ -393,6 +249,19 @@ type QueryStart = Readonly<{
393
249
  * Direction of edge traversal.
394
250
  */
395
251
  type TraversalDirection = "out" | "in";
252
+ /**
253
+ * Traversal ontology expansion behavior.
254
+ *
255
+ * - `"none"` — follow only the exact edge kind specified
256
+ * - `"implying"` — also follow edge kinds that imply the specified kind (subClassOf)
257
+ * - `"inverse"` — also follow the ontological inverse edge kind (inverseOf)
258
+ * - `"all"` — follow both implying and inverse expansions
259
+ */
260
+ type TraversalExpansion = "none" | "implying" | "inverse" | "all";
261
+ /**
262
+ * Cycle handling policy for recursive traversals.
263
+ */
264
+ type RecursiveCyclePolicy = "prevent" | "allow";
396
265
  /**
397
266
  * Variable-length traversal specification for recursive graph traversals.
398
267
  */
@@ -401,11 +270,16 @@ type VariableLengthSpec = Readonly<{
401
270
  minDepth: number;
402
271
  /** Maximum number of hops (-1 = unlimited, default: -1) */
403
272
  maxDepth: number;
404
- /** Include the traversal path as an array in results */
405
- collectPath: boolean;
406
- /** Column alias for path array (default: "{nodeAlias}_path") */
273
+ /**
274
+ * Cycle handling mode.
275
+ *
276
+ * - "prevent": Track visited nodes per path and reject revisits
277
+ * - "allow": Skip cycle checks (faster, may revisit nodes)
278
+ */
279
+ cyclePolicy: RecursiveCyclePolicy;
280
+ /** Optional column alias for projected traversal path array */
407
281
  pathAlias?: string;
408
- /** Column alias for depth (default: "{nodeAlias}_depth") */
282
+ /** Optional column alias for projected traversal depth */
409
283
  depthAlias?: string;
410
284
  }>;
411
285
  /**
@@ -414,6 +288,12 @@ type VariableLengthSpec = Readonly<{
414
288
  type Traversal = Readonly<{
415
289
  edgeAlias: string;
416
290
  edgeKinds: readonly string[];
291
+ /**
292
+ * Edge kinds traversed in the opposite direction.
293
+ *
294
+ * Populated when query options request inverse/symmetric expansion.
295
+ */
296
+ inverseEdgeKinds?: readonly string[];
417
297
  direction: TraversalDirection;
418
298
  nodeAlias: string;
419
299
  nodeKinds: readonly string[];
@@ -561,4 +441,4 @@ type SetOperation = Readonly<{
561
441
  */
562
442
  type ComposableQuery = QueryAst | SetOperation;
563
443
 
564
- export { type AnyEdgeType as A, type Traversal as B, type ComparisonOp as C, type DeleteBehavior as D, type EdgeType as E, type FieldRef as F, type GraphDefaults as G, type NodePredicate as H, type ProjectedField as I, type JsonPointer as J, type GroupBySpec as K, type TraversalDirection as L, MAX_JSON_POINTER_DEPTH as M, type NodeType as N, type OrderSpec as O, type PredicateExpression as P, type QueryAst as Q, type ResolveJsonPointer as R, type SortDirection as S, type TemporalMode as T, type UniqueConstraint as U, type ValueType as V, type ComposableQuery as W, type SetOperationType as X, type SetOperation as Y, type JsonPointerFor as a, type JsonPointerSegmentsFor as b, type AggregateExpr as c, type AggregateComparisonPredicate as d, type Cardinality as e, type Collation as f, type EdgeProps as g, type EdgeRegistration as h, type EdgeTypeWithEndpoints as i, type EndpointExistence as j, type JsonPointerInput as k, type JsonPointerSegment as l, type JsonPointerSegments as m, type NodeId as n, type NodeProps as o, type NodeRegistration as p, type ResolveJsonPointerSegments as q, type UniquenessScope as r, isEdgeType as s, isEdgeTypeWithEndpoints as t, isNodeType as u, joinJsonPointers as v, jsonPointer as w, normalizeJsonPointer as x, parseJsonPointer as y, type VectorMetricType as z };
444
+ export { type AggregateExpr as A, type ComparisonOp as C, type FieldRef as F, type GroupBySpec as G, type JsonPointer as J, MAX_JSON_POINTER_DEPTH as M, type NodePredicate as N, type OrderSpec as O, type ParameterRef as P, type QueryAst as Q, type ResolveJsonPointer as R, type SortDirection as S, type TraversalExpansion as T, type ValueType as V, type JsonPointerFor as a, type JsonPointerSegmentsFor as b, type AggregateComparisonPredicate as c, type JsonPointerInput as d, type JsonPointerSegment as e, type JsonPointerSegments as f, type ResolveJsonPointerSegments as g, jsonPointer as h, type PredicateExpression as i, joinJsonPointers as j, type VectorMetricType as k, type Traversal as l, type ProjectedField as m, normalizeJsonPointer as n, type RecursiveCyclePolicy as o, parseJsonPointer as p, type TraversalDirection as q, type SelectiveField as r, type ComposableQuery as s, type SetOperationType as t, type SetOperation as u };
@@ -1,159 +1,4 @@
1
- import { z } from 'zod';
2
-
3
- /** Brand key for NodeType */
4
- declare const NODE_TYPE_BRAND: "__nodeType";
5
- /** Brand key for EdgeType */
6
- declare const EDGE_TYPE_BRAND: "__edgeType";
7
- /** Brand symbol for NodeId */
8
- declare const __nodeId: unique symbol;
9
- /**
10
- * A node type definition.
11
- *
12
- * Created via `defineNode()`. Represents a type of node in the graph
13
- * with an associated Zod schema for properties.
14
- */
15
- type NodeType<K extends string = string, S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> = Readonly<{
16
- [NODE_TYPE_BRAND]: true;
17
- name: K;
18
- schema: S;
19
- description: string | undefined;
20
- }>;
21
- /**
22
- * Branded node ID type.
23
- *
24
- * Prevents mixing IDs from different node types at compile time.
25
- */
26
- type NodeId<N extends NodeType> = string & Readonly<{
27
- [__nodeId]: N;
28
- }>;
29
- /**
30
- * Infer the props type from a NodeType.
31
- */
32
- type NodeProps<N extends NodeType> = z.infer<N["schema"]>;
33
- /**
34
- * An edge type definition.
35
- *
36
- * Created via `defineEdge()`. Represents a type of edge in the graph
37
- * with an optional Zod schema for properties.
38
- *
39
- * Optionally includes `from` and `to` arrays that define the allowed
40
- * source and target node types (domain and range constraints).
41
- */
42
- type EdgeType<K extends string = string, S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>, From extends readonly NodeType[] | undefined = undefined, To extends readonly NodeType[] | undefined = undefined> = Readonly<{
43
- [EDGE_TYPE_BRAND]: true;
44
- name: K;
45
- schema: S;
46
- description: string | undefined;
47
- from: From;
48
- to: To;
49
- }>;
50
- /**
51
- * Base edge type for use in constraints - accepts any from/to configuration.
52
- */
53
- type AnyEdgeType = EdgeType<string, z.ZodObject<z.ZodRawShape>, readonly NodeType[] | undefined, readonly NodeType[] | undefined>;
54
- /**
55
- * An edge type that has both from and to constraints defined.
56
- * Can be used directly in defineGraph without an EdgeRegistration wrapper.
57
- */
58
- type EdgeTypeWithEndpoints = EdgeType<string, z.ZodObject<z.ZodRawShape>, readonly NodeType[], readonly NodeType[]>;
59
- /**
60
- * Infer the props type from an EdgeType.
61
- */
62
- type EdgeProps<E extends AnyEdgeType> = z.infer<E["schema"]>;
63
- /**
64
- * Delete behaviors for nodes.
65
- */
66
- type DeleteBehavior = "restrict" | "cascade" | "disconnect";
67
- /**
68
- * Edge cardinality constraints.
69
- */
70
- type Cardinality = "many" | "one" | "unique" | "oneActive";
71
- /**
72
- * Endpoint existence modes for edge validation.
73
- */
74
- type EndpointExistence = "notDeleted" | "currentlyValid" | "ever";
75
- /**
76
- * Temporal query modes.
77
- */
78
- type TemporalMode = "current" | "asOf" | "includeEnded" | "includeTombstones";
79
- /**
80
- * Uniqueness constraint scope.
81
- */
82
- type UniquenessScope = "kind" | "kindWithSubClasses";
83
- /**
84
- * Collation for uniqueness constraints.
85
- */
86
- type Collation = "binary" | "caseInsensitive";
87
- /**
88
- * Uniqueness constraint definition.
89
- */
90
- type UniqueConstraint<S extends z.ZodObject<z.ZodRawShape> = z.ZodObject<z.ZodRawShape>> = Readonly<{
91
- name: string;
92
- fields: readonly (keyof z.infer<S> & string)[];
93
- where?: (props: UniqueConstraintPredicateBuilder<S>) => UniqueConstraintPredicate;
94
- scope: UniquenessScope;
95
- collation: Collation;
96
- }>;
97
- /**
98
- * Predicate builder for uniqueness constraint where clause.
99
- * Uses -? to make all fields required in the builder, even if optional in the schema.
100
- */
101
- type UniqueConstraintPredicateBuilder<S extends z.ZodObject<z.ZodRawShape>> = Readonly<{
102
- [K in keyof z.infer<S>]-?: UniqueConstraintField;
103
- }>;
104
- /**
105
- * Field operations for uniqueness constraint predicates.
106
- */
107
- type UniqueConstraintField = Readonly<{
108
- isNull: () => UniqueConstraintPredicate;
109
- isNotNull: () => UniqueConstraintPredicate;
110
- }>;
111
- /**
112
- * A uniqueness constraint predicate (internal representation).
113
- */
114
- type UniqueConstraintPredicate = Readonly<{
115
- __type: "unique_predicate";
116
- field: string;
117
- op: "isNull" | "isNotNull";
118
- }>;
119
- /**
120
- * Node registration in a graph definition.
121
- */
122
- type NodeRegistration<N extends NodeType = NodeType> = Readonly<{
123
- type: N;
124
- unique?: readonly UniqueConstraint<N["schema"]>[];
125
- onDelete?: DeleteBehavior;
126
- }>;
127
- /**
128
- * Edge registration in a graph definition.
129
- */
130
- type EdgeRegistration<E extends AnyEdgeType = AnyEdgeType, FromTypes extends NodeType = NodeType, ToTypes extends NodeType = NodeType> = Readonly<{
131
- type: E;
132
- from: readonly FromTypes[];
133
- to: readonly ToTypes[];
134
- cardinality?: Cardinality;
135
- endpointExistence?: EndpointExistence;
136
- }>;
137
- /**
138
- * Default settings for a graph.
139
- */
140
- type GraphDefaults = Readonly<{
141
- onNodeDelete?: DeleteBehavior;
142
- temporalMode?: TemporalMode;
143
- }>;
144
- /**
145
- * Checks if a value is a NodeType.
146
- */
147
- declare function isNodeType(value: unknown): value is NodeType;
148
- /**
149
- * Checks if a value is an EdgeType.
150
- */
151
- declare function isEdgeType(value: unknown): value is AnyEdgeType;
152
- /**
153
- * Checks if a value is an EdgeType with both from and to constraints defined.
154
- * Such edges can be used directly in defineGraph without an EdgeRegistration wrapper.
155
- */
156
- declare function isEdgeTypeWithEndpoints(value: unknown): value is EdgeTypeWithEndpoints;
1
+ import { T as TemporalMode } from './types-DTJEu_-h.cjs';
157
2
 
158
3
  declare const MAX_JSON_POINTER_DEPTH: 5;
159
4
  type JsonPointer = string & {
@@ -224,6 +69,17 @@ type LiteralValue = Readonly<{
224
69
  value: string | number | boolean;
225
70
  valueType?: ValueType | undefined;
226
71
  }>;
72
+ /**
73
+ * A parameter reference for prepared queries.
74
+ *
75
+ * Used in place of a literal value to create parameterized queries
76
+ * that can be executed multiple times with different bindings.
77
+ */
78
+ type ParameterRef = Readonly<{
79
+ __type: "parameter";
80
+ name: string;
81
+ valueType?: ValueType | undefined;
82
+ }>;
227
83
  /**
228
84
  * Supported value types for predicates.
229
85
  */
@@ -243,7 +99,7 @@ type ComparisonPredicate = Readonly<{
243
99
  __type: "comparison";
244
100
  op: ComparisonOp;
245
101
  left: FieldRef;
246
- right: LiteralValue | LiteralValue[];
102
+ right: LiteralValue | LiteralValue[] | ParameterRef;
247
103
  }>;
248
104
  /**
249
105
  * A string predicate.
@@ -252,7 +108,7 @@ type StringPredicate = Readonly<{
252
108
  __type: "string_op";
253
109
  op: StringOp;
254
110
  field: FieldRef;
255
- pattern: string;
111
+ pattern: string | ParameterRef;
256
112
  }>;
257
113
  /**
258
114
  * A null check predicate.
@@ -268,8 +124,8 @@ type NullPredicate = Readonly<{
268
124
  type BetweenPredicate = Readonly<{
269
125
  __type: "between";
270
126
  field: FieldRef;
271
- lower: LiteralValue;
272
- upper: LiteralValue;
127
+ lower: LiteralValue | ParameterRef;
128
+ upper: LiteralValue | ParameterRef;
273
129
  }>;
274
130
  /**
275
131
  * Array operators.
@@ -393,6 +249,19 @@ type QueryStart = Readonly<{
393
249
  * Direction of edge traversal.
394
250
  */
395
251
  type TraversalDirection = "out" | "in";
252
+ /**
253
+ * Traversal ontology expansion behavior.
254
+ *
255
+ * - `"none"` — follow only the exact edge kind specified
256
+ * - `"implying"` — also follow edge kinds that imply the specified kind (subClassOf)
257
+ * - `"inverse"` — also follow the ontological inverse edge kind (inverseOf)
258
+ * - `"all"` — follow both implying and inverse expansions
259
+ */
260
+ type TraversalExpansion = "none" | "implying" | "inverse" | "all";
261
+ /**
262
+ * Cycle handling policy for recursive traversals.
263
+ */
264
+ type RecursiveCyclePolicy = "prevent" | "allow";
396
265
  /**
397
266
  * Variable-length traversal specification for recursive graph traversals.
398
267
  */
@@ -401,11 +270,16 @@ type VariableLengthSpec = Readonly<{
401
270
  minDepth: number;
402
271
  /** Maximum number of hops (-1 = unlimited, default: -1) */
403
272
  maxDepth: number;
404
- /** Include the traversal path as an array in results */
405
- collectPath: boolean;
406
- /** Column alias for path array (default: "{nodeAlias}_path") */
273
+ /**
274
+ * Cycle handling mode.
275
+ *
276
+ * - "prevent": Track visited nodes per path and reject revisits
277
+ * - "allow": Skip cycle checks (faster, may revisit nodes)
278
+ */
279
+ cyclePolicy: RecursiveCyclePolicy;
280
+ /** Optional column alias for projected traversal path array */
407
281
  pathAlias?: string;
408
- /** Column alias for depth (default: "{nodeAlias}_depth") */
282
+ /** Optional column alias for projected traversal depth */
409
283
  depthAlias?: string;
410
284
  }>;
411
285
  /**
@@ -414,6 +288,12 @@ type VariableLengthSpec = Readonly<{
414
288
  type Traversal = Readonly<{
415
289
  edgeAlias: string;
416
290
  edgeKinds: readonly string[];
291
+ /**
292
+ * Edge kinds traversed in the opposite direction.
293
+ *
294
+ * Populated when query options request inverse/symmetric expansion.
295
+ */
296
+ inverseEdgeKinds?: readonly string[];
417
297
  direction: TraversalDirection;
418
298
  nodeAlias: string;
419
299
  nodeKinds: readonly string[];
@@ -561,4 +441,4 @@ type SetOperation = Readonly<{
561
441
  */
562
442
  type ComposableQuery = QueryAst | SetOperation;
563
443
 
564
- export { type AnyEdgeType as A, type Traversal as B, type ComparisonOp as C, type DeleteBehavior as D, type EdgeType as E, type FieldRef as F, type GraphDefaults as G, type NodePredicate as H, type ProjectedField as I, type JsonPointer as J, type GroupBySpec as K, type TraversalDirection as L, MAX_JSON_POINTER_DEPTH as M, type NodeType as N, type OrderSpec as O, type PredicateExpression as P, type QueryAst as Q, type ResolveJsonPointer as R, type SortDirection as S, type TemporalMode as T, type UniqueConstraint as U, type ValueType as V, type ComposableQuery as W, type SetOperationType as X, type SetOperation as Y, type JsonPointerFor as a, type JsonPointerSegmentsFor as b, type AggregateExpr as c, type AggregateComparisonPredicate as d, type Cardinality as e, type Collation as f, type EdgeProps as g, type EdgeRegistration as h, type EdgeTypeWithEndpoints as i, type EndpointExistence as j, type JsonPointerInput as k, type JsonPointerSegment as l, type JsonPointerSegments as m, type NodeId as n, type NodeProps as o, type NodeRegistration as p, type ResolveJsonPointerSegments as q, type UniquenessScope as r, isEdgeType as s, isEdgeTypeWithEndpoints as t, isNodeType as u, joinJsonPointers as v, jsonPointer as w, normalizeJsonPointer as x, parseJsonPointer as y, type VectorMetricType as z };
444
+ export { type AggregateExpr as A, type ComparisonOp as C, type FieldRef as F, type GroupBySpec as G, type JsonPointer as J, MAX_JSON_POINTER_DEPTH as M, type NodePredicate as N, type OrderSpec as O, type ParameterRef as P, type QueryAst as Q, type ResolveJsonPointer as R, type SortDirection as S, type TraversalExpansion as T, type ValueType as V, type JsonPointerFor as a, type JsonPointerSegmentsFor as b, type AggregateComparisonPredicate as c, type JsonPointerInput as d, type JsonPointerSegment as e, type JsonPointerSegments as f, type ResolveJsonPointerSegments as g, jsonPointer as h, type PredicateExpression as i, joinJsonPointers as j, type VectorMetricType as k, type Traversal as l, type ProjectedField as m, normalizeJsonPointer as n, type RecursiveCyclePolicy as o, parseJsonPointer as p, type TraversalDirection as q, type SelectiveField as r, type ComposableQuery as s, type SetOperationType as t, type SetOperation as u };
@@ -1,41 +1,40 @@
1
1
  'use strict';
2
2
 
3
- var chunkTXHKFLWX_cjs = require('../../chunk-TXHKFLWX.cjs');
4
- var chunkUJAGXJDG_cjs = require('../../chunk-UJAGXJDG.cjs');
5
- var chunkMFVCSNIY_cjs = require('../../chunk-MFVCSNIY.cjs');
6
- require('../../chunk-F32HCHYA.cjs');
7
- var chunkN4AOJ3VF_cjs = require('../../chunk-N4AOJ3VF.cjs');
8
- require('../../chunk-SV5H3XM5.cjs');
9
- require('../../chunk-DDM2FZRJ.cjs');
10
- require('../../chunk-YM5AL65Y.cjs');
3
+ var chunkCMHFS34N_cjs = require('../../chunk-CMHFS34N.cjs');
4
+ var chunkV7CS2MDB_cjs = require('../../chunk-V7CS2MDB.cjs');
5
+ require('../../chunk-SFY2PPOY.cjs');
6
+ var chunkXZL6MCZJ_cjs = require('../../chunk-XZL6MCZJ.cjs');
7
+ var chunkNU2XNMVI_cjs = require('../../chunk-NU2XNMVI.cjs');
8
+ require('../../chunk-OYL2SGBD.cjs');
9
+ require('../../chunk-JQDWEX6V.cjs');
10
+ require('../../chunk-2WVFEIHR.cjs');
11
11
  require('../../chunk-P5CNM325.cjs');
12
- require('../../chunk-JEQ2X3Z6.cjs');
13
12
 
14
13
 
15
14
 
16
- Object.defineProperty(exports, "createPostgresBackend", {
15
+ Object.defineProperty(exports, "createSqliteBackend", {
17
16
  enumerable: true,
18
- get: function () { return chunkTXHKFLWX_cjs.createPostgresBackend; }
17
+ get: function () { return chunkCMHFS34N_cjs.createSqliteBackend; }
19
18
  });
20
- Object.defineProperty(exports, "createPostgresTables", {
19
+ Object.defineProperty(exports, "createPostgresBackend", {
21
20
  enumerable: true,
22
- get: function () { return chunkUJAGXJDG_cjs.createPostgresTables; }
21
+ get: function () { return chunkV7CS2MDB_cjs.createPostgresBackend; }
23
22
  });
24
- Object.defineProperty(exports, "postgresTables", {
23
+ Object.defineProperty(exports, "createSqliteTables", {
25
24
  enumerable: true,
26
- get: function () { return chunkUJAGXJDG_cjs.tables; }
25
+ get: function () { return chunkXZL6MCZJ_cjs.createSqliteTables; }
27
26
  });
28
- Object.defineProperty(exports, "createSqliteBackend", {
27
+ Object.defineProperty(exports, "sqliteTables", {
29
28
  enumerable: true,
30
- get: function () { return chunkMFVCSNIY_cjs.createSqliteBackend; }
29
+ get: function () { return chunkXZL6MCZJ_cjs.tables; }
31
30
  });
32
- Object.defineProperty(exports, "createSqliteTables", {
31
+ Object.defineProperty(exports, "createPostgresTables", {
33
32
  enumerable: true,
34
- get: function () { return chunkN4AOJ3VF_cjs.createSqliteTables; }
33
+ get: function () { return chunkNU2XNMVI_cjs.createPostgresTables; }
35
34
  });
36
- Object.defineProperty(exports, "sqliteTables", {
35
+ Object.defineProperty(exports, "postgresTables", {
37
36
  enumerable: true,
38
- get: function () { return chunkN4AOJ3VF_cjs.tables; }
37
+ get: function () { return chunkNU2XNMVI_cjs.tables; }
39
38
  });
40
39
  //# sourceMappingURL=index.cjs.map
41
40
  //# sourceMappingURL=index.cjs.map
@@ -2,11 +2,12 @@ export { SqliteBackendOptions, createSqliteBackend } from './sqlite.cjs';
2
2
  export { PostgresBackendOptions, createPostgresBackend } from './postgres.cjs';
3
3
  export { PostgresTables, createPostgresTables, tables as postgresTables } from './schema/postgres.cjs';
4
4
  export { SqliteTables, createSqliteTables, tables as sqliteTables } from './schema/sqlite.cjs';
5
- import 'drizzle-orm/sqlite-core';
6
- import '../../types-DDOSfrih.cjs';
5
+ import '../../types-DDP0MGBF.cjs';
7
6
  import 'drizzle-orm';
7
+ import '../../types-DTJEu_-h.cjs';
8
+ import 'zod';
8
9
  import '../../types-BRzHlhKC.cjs';
10
+ import 'drizzle-orm/sqlite-core';
9
11
  import 'drizzle-orm/pg-core';
10
- import '../../types-a5rAxC92.cjs';
11
- import 'zod';
12
- import '../../ast-BVyihVbP.cjs';
12
+ import '../../types-DHRsi6j9.cjs';
13
+ import '../../ast-D-3bOanX.cjs';
@@ -2,11 +2,12 @@ export { SqliteBackendOptions, createSqliteBackend } from './sqlite.js';
2
2
  export { PostgresBackendOptions, createPostgresBackend } from './postgres.js';
3
3
  export { PostgresTables, createPostgresTables, tables as postgresTables } from './schema/postgres.js';
4
4
  export { SqliteTables, createSqliteTables, tables as sqliteTables } from './schema/sqlite.js';
5
- import 'drizzle-orm/sqlite-core';
6
- import '../../types-CjZ7g_7v.js';
5
+ import '../../types-Cdbi4hcx.js';
7
6
  import 'drizzle-orm';
7
+ import '../../types-DTJEu_-h.js';
8
+ import 'zod';
8
9
  import '../../types-BRzHlhKC.js';
10
+ import 'drizzle-orm/sqlite-core';
9
11
  import 'drizzle-orm/pg-core';
10
- import '../../types-CX4cLd7M.js';
11
- import 'zod';
12
- import '../../ast-BVyihVbP.js';
12
+ import '../../types-ZT5mlism.js';
13
+ import '../../ast-CXFx6bF6.js';