@cyphra/runtime 0.4.0 → 0.6.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.
- package/README.md +3 -0
- package/dist/index.d.ts +378 -16
- package/dist/index.js +864 -35
- package/dist/index.js.map +1 -1
- package/package.json +9 -4
package/README.md
CHANGED
|
@@ -4,6 +4,9 @@
|
|
|
4
4
|
|
|
5
5
|
Neo4j driver wrapper for Cyphra: sessions, transactions, and safe execution of compiled Cypher.
|
|
6
6
|
|
|
7
|
+
Works with `neo4j-driver` **5.28+ and 6.x**, a peer dependency (`npm i @cyphra/runtime neo4j-driver`).
|
|
8
|
+
Pass `{ driver }` instead of a URI to reuse a `Driver` your app already has.
|
|
9
|
+
|
|
7
10
|
```ts
|
|
8
11
|
import { CyphraClient } from "@cyphra/runtime";
|
|
9
12
|
import { cypher } from "@cyphra/query";
|
package/dist/index.d.ts
CHANGED
|
@@ -4,18 +4,61 @@ import { CompiledCypher, SelectQuery } from '@cyphra/query';
|
|
|
4
4
|
import { SchemaModel } from '@cyphra/schema';
|
|
5
5
|
export { SchemaModel } from '@cyphra/schema';
|
|
6
6
|
|
|
7
|
-
type
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
7
|
+
type Params = Record<string, unknown>;
|
|
8
|
+
/**
|
|
9
|
+
* Minimal structural shape of a `neo4j-driver` managed transaction, as Cyphra uses it.
|
|
10
|
+
* Declared structurally so transactions from either supported driver major (5.x or 6.x) fit.
|
|
11
|
+
*/
|
|
12
|
+
interface TransactionLike {
|
|
13
|
+
run(query: string, parameters?: Params): PromiseLike<unknown>;
|
|
14
|
+
}
|
|
15
|
+
/** Minimal structural shape of a `neo4j-driver` session, as Cyphra uses it. */
|
|
16
|
+
interface SessionLike {
|
|
17
|
+
run(query: string, parameters?: Params): PromiseLike<unknown>;
|
|
18
|
+
executeRead<T>(work: (tx: TransactionLike) => Promise<T> | T): Promise<T>;
|
|
19
|
+
executeWrite<T>(work: (tx: TransactionLike) => Promise<T> | T): Promise<T>;
|
|
20
|
+
close(): Promise<void>;
|
|
21
|
+
}
|
|
22
|
+
/**
|
|
23
|
+
* Minimal structural shape of a `neo4j-driver` `Driver`. Any `Driver` from `neo4j-driver` 5.28+ or
|
|
24
|
+
* 6.x satisfies it, even when it comes from a different copy of the package than the one Cyphra
|
|
25
|
+
* resolves (the driver's classes are not structurally assignable across copies, this type is).
|
|
26
|
+
*/
|
|
27
|
+
interface DriverLike {
|
|
28
|
+
session(config?: {
|
|
29
|
+
database?: string;
|
|
30
|
+
}): SessionLike;
|
|
31
|
+
close(): Promise<void>;
|
|
32
|
+
}
|
|
33
|
+
type CommonClientOptions = {
|
|
12
34
|
/** Optional database name (Neo4j 4+). */
|
|
13
35
|
database?: string;
|
|
14
36
|
/** When true, logs compiled Cypher and parameter keys (never values). */
|
|
15
37
|
debug?: boolean;
|
|
38
|
+
};
|
|
39
|
+
/** Connect with a URI and credentials: the client creates (and owns) its own driver. */
|
|
40
|
+
type CyphraConnectionOptions = CommonClientOptions & {
|
|
41
|
+
/** Bolt / Neo4j URI, e.g. `neo4j+s://xxx.databases.neo4j.io`. */
|
|
42
|
+
uri: string;
|
|
43
|
+
user: string;
|
|
44
|
+
password: string;
|
|
16
45
|
/** Third argument to `neo4j.driver` — pool size, acquisition timeout, logging, etc. */
|
|
17
46
|
driverConfig?: Config;
|
|
47
|
+
driver?: never;
|
|
18
48
|
};
|
|
49
|
+
/**
|
|
50
|
+
* Reuse a `Driver` your application already created (`neo4j-driver` 5.28+ or 6.x). The client
|
|
51
|
+
* shares its connection pool and never closes it: {@link CyphraClient.close} is a no-op, close
|
|
52
|
+
* the driver yourself on shutdown.
|
|
53
|
+
*/
|
|
54
|
+
type CyphraDriverOptions = CommonClientOptions & {
|
|
55
|
+
driver: DriverLike;
|
|
56
|
+
uri?: never;
|
|
57
|
+
user?: never;
|
|
58
|
+
password?: never;
|
|
59
|
+
driverConfig?: never;
|
|
60
|
+
};
|
|
61
|
+
type CyphraClientOptions = CyphraConnectionOptions | CyphraDriverOptions;
|
|
19
62
|
/**
|
|
20
63
|
* Thin facade over `neo4j-driver`: sessions, transactions, and the Cyphra `cypher` tag.
|
|
21
64
|
*
|
|
@@ -34,10 +77,14 @@ type CyphraClientOptions = {
|
|
|
34
77
|
* await session.close();
|
|
35
78
|
* }
|
|
36
79
|
* await client.close();
|
|
80
|
+
*
|
|
81
|
+
* // Or share a driver your app already has (neo4j-driver 5.28+ or 6.x):
|
|
82
|
+
* const shared = new CyphraClient({ driver: neo4j.driver(uri, neo4j.auth.basic(user, password)) });
|
|
37
83
|
* ```
|
|
38
84
|
*/
|
|
39
85
|
declare class CyphraClient {
|
|
40
86
|
private readonly driver;
|
|
87
|
+
private readonly ownsDriver;
|
|
41
88
|
private readonly database?;
|
|
42
89
|
private readonly debug;
|
|
43
90
|
constructor(opts: CyphraClientOptions);
|
|
@@ -104,7 +151,10 @@ declare class CyphraClient {
|
|
|
104
151
|
* Execute work inside a read transaction.
|
|
105
152
|
*/
|
|
106
153
|
withReadTransaction<T>(fn: (tx: ManagedTransaction) => Promise<T>): Promise<T>;
|
|
107
|
-
/**
|
|
154
|
+
/**
|
|
155
|
+
* Close the driver (call on shutdown). A driver passed in with `{ driver }` is left open: its
|
|
156
|
+
* owner closes it.
|
|
157
|
+
*/
|
|
108
158
|
close(): Promise<void>;
|
|
109
159
|
}
|
|
110
160
|
|
|
@@ -227,11 +277,19 @@ type WhereUniqueInput<TM extends TypeMap, M extends keyof TM> = RequireAtLeastOn
|
|
|
227
277
|
[K in TM[M]["unique"] & keyof Scalars<TM, M>]: NonNullable<Scalars<TM, M>[K]>;
|
|
228
278
|
}> & WhereInput<TM, M>;
|
|
229
279
|
type SortOrder = "asc" | "desc";
|
|
230
|
-
|
|
231
|
-
|
|
232
|
-
|
|
280
|
+
/** Keys of the to-many relations of model `M` (the ones `_count` can count). */
|
|
281
|
+
type ToManyRelations<TM extends TypeMap, M extends keyof TM> = {
|
|
282
|
+
[R in keyof Relations<TM, M> & string]: Rel<TM, M, R>["many"] extends true ? R : never;
|
|
283
|
+
}[keyof Relations<TM, M> & string];
|
|
284
|
+
/** One `orderBy` entry: scalars, or a to-many relation by its count (`{ posts: { _count: "desc" } }`). */
|
|
285
|
+
type OrderByItem<TM extends TypeMap, M extends keyof TM> = {
|
|
233
286
|
[K in keyof Scalars<TM, M>]?: SortOrder;
|
|
234
|
-
}
|
|
287
|
+
} & {
|
|
288
|
+
[R in ToManyRelations<TM, M>]?: {
|
|
289
|
+
_count?: SortOrder;
|
|
290
|
+
};
|
|
291
|
+
};
|
|
292
|
+
type OrderByInput<TM extends TypeMap, M extends keyof TM> = OrderByItem<TM, M> | readonly OrderByItem<TM, M>[];
|
|
235
293
|
/** Options for loading a relation inside `select` / `include`. */
|
|
236
294
|
type RelationLoadArgs<TM extends TypeMap, T extends keyof TM> = {
|
|
237
295
|
where?: WhereInput<TM, T>;
|
|
@@ -241,13 +299,30 @@ type RelationLoadArgs<TM extends TypeMap, T extends keyof TM> = {
|
|
|
241
299
|
select?: SelectInput<TM, T>;
|
|
242
300
|
include?: IncludeInput<TM, T>;
|
|
243
301
|
};
|
|
302
|
+
/**
|
|
303
|
+
* `_count` in `select` / `include`: `true` counts every to-many relation;
|
|
304
|
+
* `{ select: { posts: true, comments: { where } } }` counts the listed ones (optionally filtered).
|
|
305
|
+
*/
|
|
306
|
+
type RelationCountInput<TM extends TypeMap, M extends keyof TM> = boolean | {
|
|
307
|
+
select: {
|
|
308
|
+
[R in keyof Relations<TM, M>]?: R extends ToManyRelations<TM, M> ? boolean | {
|
|
309
|
+
where?: WhereInput<TM, Target<TM, M, R>>;
|
|
310
|
+
} : never;
|
|
311
|
+
};
|
|
312
|
+
};
|
|
244
313
|
type SelectInput<TM extends TypeMap, M extends keyof TM> = {
|
|
245
314
|
[K in keyof Scalars<TM, M>]?: boolean;
|
|
246
315
|
} & {
|
|
247
316
|
[R in keyof Relations<TM, M>]?: boolean | RelationLoadArgs<TM, Target<TM, M, R>>;
|
|
317
|
+
} & {
|
|
318
|
+
/** Number of related nodes per to-many relation. */
|
|
319
|
+
_count?: RelationCountInput<TM, M>;
|
|
248
320
|
};
|
|
249
321
|
type IncludeInput<TM extends TypeMap, M extends keyof TM> = {
|
|
250
322
|
[R in keyof Relations<TM, M>]?: boolean | RelationLoadArgs<TM, Target<TM, M, R>>;
|
|
323
|
+
} & {
|
|
324
|
+
/** Number of related nodes per to-many relation. */
|
|
325
|
+
_count?: RelationCountInput<TM, M>;
|
|
251
326
|
};
|
|
252
327
|
type EdgePart<D extends RelationTypeDef> = D["edge"] extends Record<string, unknown> ? {
|
|
253
328
|
$edge: D["edge"];
|
|
@@ -256,14 +331,25 @@ type RelationPayload<TM extends TypeMap, D extends RelationTypeDef, A> = D["many
|
|
|
256
331
|
type TrueKeys<T> = {
|
|
257
332
|
[K in keyof T]: T[K] extends false | undefined ? never : K;
|
|
258
333
|
}[keyof T];
|
|
334
|
+
/** `{ posts: number, … }` for a `_count` selection `C`. */
|
|
335
|
+
type RelationCountPayload<TM extends TypeMap, M extends keyof TM, C> = C extends true ? {
|
|
336
|
+
[R in ToManyRelations<TM, M>]: number;
|
|
337
|
+
} : C extends {
|
|
338
|
+
select: infer X;
|
|
339
|
+
} ? {
|
|
340
|
+
[R in TrueKeys<X> & ToManyRelations<TM, M>]: number;
|
|
341
|
+
} : never;
|
|
342
|
+
type CountPart<TM extends TypeMap, M extends keyof TM, A> = "_count" extends TrueKeys<A> ? {
|
|
343
|
+
_count: Simplify<RelationCountPayload<TM, M, A["_count" & keyof A]>>;
|
|
344
|
+
} : unknown;
|
|
259
345
|
type SelectPayload<TM extends TypeMap, M extends keyof TM, S> = {
|
|
260
346
|
[K in TrueKeys<S> & keyof Scalars<TM, M>]: Scalars<TM, M>[K];
|
|
261
347
|
} & {
|
|
262
348
|
[R in TrueKeys<S> & keyof Relations<TM, M>]: RelationPayload<TM, Rel<TM, M, R>, S[R & keyof S] extends object ? S[R & keyof S] : object>;
|
|
263
|
-
}
|
|
349
|
+
} & CountPart<TM, M, S>;
|
|
264
350
|
type IncludePayload<TM extends TypeMap, M extends keyof TM, I> = Scalars<TM, M> & {
|
|
265
351
|
[R in TrueKeys<I> & keyof Relations<TM, M>]: RelationPayload<TM, Rel<TM, M, R>, I[R & keyof I] extends object ? I[R & keyof I] : object>;
|
|
266
|
-
}
|
|
352
|
+
} & CountPart<TM, M, I>;
|
|
267
353
|
/** Result type of a query on model `M` with args `A` (honours `select` / `include`). */
|
|
268
354
|
type Payload<TM extends TypeMap, M extends keyof TM, A> = Simplify<IsObject<ArgOf<A, "select">> extends true ? SelectPayload<TM, M, ArgOf<A, "select">> : IsObject<ArgOf<A, "include">> extends true ? IncludePayload<TM, M, ArgOf<A, "include">> : Scalars<TM, M>>;
|
|
269
355
|
type IsObject<X> = [X] extends [never] ? false : [X] extends [object] ? true : false;
|
|
@@ -354,6 +440,245 @@ type CountArgs<TM extends TypeMap, M extends keyof TM> = {
|
|
|
354
440
|
type BatchResult = {
|
|
355
441
|
count: number;
|
|
356
442
|
};
|
|
443
|
+
type ScalarKeys<TM extends TypeMap, M extends keyof TM> = keyof Scalars<TM, M> & string;
|
|
444
|
+
/** Scalar keys whose (non-null) type is `number` (`Int`, `Float`): valid for `_sum` / `_avg`. */
|
|
445
|
+
type NumericKeys<TM extends TypeMap, M extends keyof TM> = {
|
|
446
|
+
[K in ScalarKeys<TM, M>]: NonNullable<Scalars<TM, M>[K]> extends number ? K : never;
|
|
447
|
+
}[ScalarKeys<TM, M>];
|
|
448
|
+
/** Scalar keys of `Int`, `Float`, `String`, `DateTime` and `Date` fields: valid for `_min` / `_max`. */
|
|
449
|
+
type MinMaxKeys<TM extends TypeMap, M extends keyof TM> = {
|
|
450
|
+
[K in ScalarKeys<TM, M>]: NonNullable<Scalars<TM, M>[K]> extends number | string | Date ? K : never;
|
|
451
|
+
}[ScalarKeys<TM, M>];
|
|
452
|
+
/** Rejects keys outside `Allowed` (TypeScript does not check excess keys of inferred generics). */
|
|
453
|
+
type OnlyKeys<T, Allowed extends PropertyKey> = {
|
|
454
|
+
[K in keyof T]: K extends Allowed ? T[K] : never;
|
|
455
|
+
};
|
|
456
|
+
/** `_count: { _all: true, email: true }`: `_all` counts nodes, a field counts non-null values. */
|
|
457
|
+
type CountAggregateInput<TM extends TypeMap, M extends keyof TM> = {
|
|
458
|
+
[K in ScalarKeys<TM, M> | "_all"]?: boolean;
|
|
459
|
+
};
|
|
460
|
+
type AggregateFieldsInput<K extends PropertyKey> = {
|
|
461
|
+
[P in K]?: boolean;
|
|
462
|
+
};
|
|
463
|
+
type CountSel<TM extends TypeMap, M extends keyof TM> = true | CountAggregateInput<TM, M> | undefined;
|
|
464
|
+
type FieldSel<K extends PropertyKey> = AggregateFieldsInput<K> | undefined;
|
|
465
|
+
/**
|
|
466
|
+
* The aggregate selections, each captured as its own type parameter (like `select` / `include`)
|
|
467
|
+
* so the result type follows them exactly while the other arguments keep excess-property checks.
|
|
468
|
+
*/
|
|
469
|
+
type AggregateProjection<TM extends TypeMap, M extends keyof TM, C, Su, Av, Mi, Ma> = {
|
|
470
|
+
/** `true`: number of nodes. An object: `_all` (nodes) and/or fields (non-null values). */
|
|
471
|
+
_count?: C extends object ? C & OnlyKeys<C, ScalarKeys<TM, M> | "_all"> : C;
|
|
472
|
+
/** Sum of non-null values (`Int` / `Float`); `null` when there are none. */
|
|
473
|
+
_sum?: Su & OnlyKeys<Su, NumericKeys<TM, M>>;
|
|
474
|
+
/** Mean of non-null values (`Int` / `Float`); `null` when there are none. */
|
|
475
|
+
_avg?: Av & OnlyKeys<Av, NumericKeys<TM, M>>;
|
|
476
|
+
/** Smallest non-null value (`Int`, `Float`, `String`, `DateTime`, `Date`). */
|
|
477
|
+
_min?: Mi & OnlyKeys<Mi, MinMaxKeys<TM, M>>;
|
|
478
|
+
/** Largest non-null value (`Int`, `Float`, `String`, `DateTime`, `Date`). */
|
|
479
|
+
_max?: Ma & OnlyKeys<Ma, MinMaxKeys<TM, M>>;
|
|
480
|
+
};
|
|
481
|
+
type CountOut<C> = C extends true ? number : {
|
|
482
|
+
[K in TrueKeys<C>]: number;
|
|
483
|
+
};
|
|
484
|
+
type AggOut<Sel, V> = {
|
|
485
|
+
[K in TrueKeys<Sel>]: V;
|
|
486
|
+
};
|
|
487
|
+
type ValueOut<TM extends TypeMap, M extends keyof TM, Sel> = {
|
|
488
|
+
[K in TrueKeys<Sel> & keyof Scalars<TM, M>]: NonNullable<Scalars<TM, M>[K]> | null;
|
|
489
|
+
};
|
|
490
|
+
/** Result of the aggregate part (`_count`, `_sum`, …) of `aggregate` / `groupBy`. */
|
|
491
|
+
type AggregateResult<TM extends TypeMap, M extends keyof TM, C, Su, Av, Mi, Ma> = Simplify<([C] extends [undefined] ? unknown : {
|
|
492
|
+
_count: CountOut<Exclude<C, undefined>>;
|
|
493
|
+
}) & ([Su] extends [undefined] ? unknown : {
|
|
494
|
+
_sum: AggOut<Su, number | null>;
|
|
495
|
+
}) & ([Av] extends [undefined] ? unknown : {
|
|
496
|
+
_avg: AggOut<Av, number | null>;
|
|
497
|
+
}) & ([Mi] extends [undefined] ? unknown : {
|
|
498
|
+
_min: ValueOut<TM, M, Mi>;
|
|
499
|
+
}) & ([Ma] extends [undefined] ? unknown : {
|
|
500
|
+
_max: ValueOut<TM, M, Ma>;
|
|
501
|
+
})>;
|
|
502
|
+
type AggregateArgs<TM extends TypeMap, M extends keyof TM> = {
|
|
503
|
+
where?: WhereInput<TM, M>;
|
|
504
|
+
/** With `skip` / `take`: aggregate over this window of matching nodes only. */
|
|
505
|
+
orderBy?: OrderByInput<TM, M>;
|
|
506
|
+
skip?: number;
|
|
507
|
+
take?: number;
|
|
508
|
+
};
|
|
509
|
+
type ToOneRelations<TM extends TypeMap, M extends keyof TM> = {
|
|
510
|
+
[R in keyof Relations<TM, M> & string]: Rel<TM, M, R>["many"] extends true ? never : R;
|
|
511
|
+
}[keyof Relations<TM, M> & string];
|
|
512
|
+
/**
|
|
513
|
+
* A field `groupBy` can group on: a scalar of the model, or `"relation.field"` for a scalar of a
|
|
514
|
+
* to-one related node (e.g. `"author.name"`).
|
|
515
|
+
*/
|
|
516
|
+
type GroupByField<TM extends TypeMap, M extends keyof TM> = ScalarKeys<TM, M> | {
|
|
517
|
+
[R in ToOneRelations<TM, M>]: `${R}.${keyof Scalars<TM, Target<TM, M, R>> & string}`;
|
|
518
|
+
}[ToOneRelations<TM, M>];
|
|
519
|
+
type ByScalar<B> = B extends `${string}.${string}` ? never : B;
|
|
520
|
+
type ByRelation<B> = B extends `${infer R}.${string}` ? R : never;
|
|
521
|
+
type ByRelField<B, R extends string> = B extends `${R}.${infer F}` ? F : never;
|
|
522
|
+
/** The `by` part of one `groupBy` row: `{ status, author: { name } }`. */
|
|
523
|
+
type GroupByKeys<TM extends TypeMap, M extends keyof TM, B> = {
|
|
524
|
+
[K in ByScalar<B> & keyof Scalars<TM, M>]: Scalars<TM, M>[K];
|
|
525
|
+
} & {
|
|
526
|
+
[R in ByRelation<B> & keyof Relations<TM, M>]: {
|
|
527
|
+
[F in ByRelField<B, R & string> & keyof Scalars<TM, Target<TM, M, R>>]: Scalars<TM, Target<TM, M, R>>[F] | null;
|
|
528
|
+
};
|
|
529
|
+
};
|
|
530
|
+
type FilterObject<T> = Exclude<ScalarFilter<T>, T>;
|
|
531
|
+
/** Filters on one aggregate of field `K`, for `having`. */
|
|
532
|
+
type HavingAggregates<TM extends TypeMap, M extends keyof TM, K> = {
|
|
533
|
+
_count?: ScalarFilter<number>;
|
|
534
|
+
} & (K extends NumericKeys<TM, M> ? {
|
|
535
|
+
_sum?: ScalarFilter<number | null>;
|
|
536
|
+
_avg?: ScalarFilter<number | null>;
|
|
537
|
+
} : unknown) & (K extends MinMaxKeys<TM, M> ? {
|
|
538
|
+
_min?: ScalarFilter<NonNullable<Scalars<TM, M>[K & keyof Scalars<TM, M>]> | null>;
|
|
539
|
+
_max?: ScalarFilter<NonNullable<Scalars<TM, M>[K & keyof Scalars<TM, M>]> | null>;
|
|
540
|
+
} : unknown);
|
|
541
|
+
/**
|
|
542
|
+
* `having` on a `groupBy`: aggregates of any scalar (`{ views: { _avg: { gt: 10 } } }`), and plain
|
|
543
|
+
* filters on the fields listed in `by` (`{ status: "draft" }`, `{ author: { name: { not: null } } }`).
|
|
544
|
+
*/
|
|
545
|
+
type HavingInput<TM extends TypeMap, M extends keyof TM, B> = {
|
|
546
|
+
[K in ScalarKeys<TM, M>]?: K extends B ? Scalars<TM, M>[K] | (FilterObject<Scalars<TM, M>[K]> & HavingAggregates<TM, M, K>) : HavingAggregates<TM, M, K>;
|
|
547
|
+
} & {
|
|
548
|
+
[R in ByRelation<B> & keyof Relations<TM, M>]?: {
|
|
549
|
+
[F in ByRelField<B, R & string> & keyof Scalars<TM, Target<TM, M, R>>]?: ScalarFilter<Scalars<TM, Target<TM, M, R>>[F]>;
|
|
550
|
+
};
|
|
551
|
+
} & {
|
|
552
|
+
AND?: HavingInput<TM, M, B> | readonly HavingInput<TM, M, B>[];
|
|
553
|
+
OR?: readonly HavingInput<TM, M, B>[];
|
|
554
|
+
NOT?: HavingInput<TM, M, B> | readonly HavingInput<TM, M, B>[];
|
|
555
|
+
};
|
|
556
|
+
type GroupByOrderItem<TM extends TypeMap, M extends keyof TM, B> = {
|
|
557
|
+
[K in ByScalar<B> & ScalarKeys<TM, M>]?: SortOrder;
|
|
558
|
+
} & {
|
|
559
|
+
[R in ByRelation<B> & keyof Relations<TM, M>]?: {
|
|
560
|
+
[F in ByRelField<B, R & string>]?: SortOrder;
|
|
561
|
+
};
|
|
562
|
+
} & {
|
|
563
|
+
_count?: {
|
|
564
|
+
[K in ScalarKeys<TM, M> | "_all"]?: SortOrder;
|
|
565
|
+
};
|
|
566
|
+
_sum?: {
|
|
567
|
+
[K in NumericKeys<TM, M>]?: SortOrder;
|
|
568
|
+
};
|
|
569
|
+
_avg?: {
|
|
570
|
+
[K in NumericKeys<TM, M>]?: SortOrder;
|
|
571
|
+
};
|
|
572
|
+
_min?: {
|
|
573
|
+
[K in MinMaxKeys<TM, M>]?: SortOrder;
|
|
574
|
+
};
|
|
575
|
+
_max?: {
|
|
576
|
+
[K in MinMaxKeys<TM, M>]?: SortOrder;
|
|
577
|
+
};
|
|
578
|
+
};
|
|
579
|
+
/** `orderBy` on a `groupBy`: fields listed in `by`, or aggregates (`{ _count: { id: "desc" } }`). */
|
|
580
|
+
type GroupByOrderByInput<TM extends TypeMap, M extends keyof TM, B> = GroupByOrderItem<TM, M, B> | readonly GroupByOrderItem<TM, M, B>[];
|
|
581
|
+
type GroupByArgs<TM extends TypeMap, M extends keyof TM, B> = {
|
|
582
|
+
/** Fields to group on: `"status"`, `["status", "author.name"]`. */
|
|
583
|
+
by: B | readonly B[];
|
|
584
|
+
where?: WhereInput<TM, M>;
|
|
585
|
+
having?: HavingInput<TM, M, NoInfer<B>>;
|
|
586
|
+
orderBy?: GroupByOrderByInput<TM, M, NoInfer<B>>;
|
|
587
|
+
skip?: number;
|
|
588
|
+
take?: number;
|
|
589
|
+
};
|
|
590
|
+
/** One row of a `groupBy` result. */
|
|
591
|
+
type GroupByRow<TM extends TypeMap, M extends keyof TM, B, C, Su, Av, Mi, Ma> = Simplify<GroupByKeys<TM, M, B> & AggregateResult<TM, M, C, Su, Av, Mi, Ma>>;
|
|
592
|
+
/** Edge properties of a relation: its `relationship { … }` model, or `{}` when the edge is untyped. */
|
|
593
|
+
type EdgeProps<D extends RelationTypeDef> = D extends unknown ? D["edge"] extends Record<string, unknown> ? D["edge"] : Record<string, never> : never;
|
|
594
|
+
/** One relationship of a {@link Path}: `edges[i]` joins `nodes[i]` and `nodes[i + 1]`. */
|
|
595
|
+
type PathEdge<P = Record<string, unknown>> = {
|
|
596
|
+
/** Neo4j relationship type, e.g. `"FOLLOWS"`. */
|
|
597
|
+
type: string;
|
|
598
|
+
/** `"out"`: the edge points from `nodes[i]` to `nodes[i + 1]`; `"in"`: the other way round. */
|
|
599
|
+
direction: "out" | "in";
|
|
600
|
+
/** Edge properties, typed from the `relationship { … }` model (`{}` for an untyped edge). */
|
|
601
|
+
properties: P;
|
|
602
|
+
};
|
|
603
|
+
/**
|
|
604
|
+
* A path through the graph: `nodes[0] -edges[0]- nodes[1] -edges[1]- …`. `edges.length` is the
|
|
605
|
+
* number of hops and `nodes.length` is always `edges.length + 1`. Nodes carry their scalar fields.
|
|
606
|
+
*/
|
|
607
|
+
type Path<N = Record<string, unknown>, E = PathEdge> = {
|
|
608
|
+
nodes: N[];
|
|
609
|
+
edges: E[];
|
|
610
|
+
};
|
|
611
|
+
/** A {@link Path} of `M` nodes joined by edges of the relations `R` of `M`. */
|
|
612
|
+
type ModelPath<TM extends TypeMap, M extends keyof TM, R extends keyof Relations<TM, M>> = Path<Simplify<Scalars<TM, M>>, PathEdge<EdgeProps<Rel<TM, M, R>>>>;
|
|
613
|
+
/** Relations of `M` that lead back to `M` (e.g. `User.following`): the ones a traversal repeats. */
|
|
614
|
+
type SelfRelations<TM extends TypeMap, M extends keyof TM> = {
|
|
615
|
+
[R in keyof Relations<TM, M> & string]: [Rel<TM, M, R>["target"]] extends [M] ? R : never;
|
|
616
|
+
}[keyof Relations<TM, M> & string];
|
|
617
|
+
/** Filter on edge properties: scalar filters, `AND`, `OR`, `NOT`. */
|
|
618
|
+
type EdgeWhereInput<E> = {
|
|
619
|
+
[K in keyof E]?: ScalarFilter<E[K]>;
|
|
620
|
+
} & {
|
|
621
|
+
AND?: EdgeWhereInput<E> | readonly EdgeWhereInput<E>[];
|
|
622
|
+
OR?: readonly EdgeWhereInput<E>[];
|
|
623
|
+
NOT?: EdgeWhereInput<E> | readonly EdgeWhereInput<E>[];
|
|
624
|
+
};
|
|
625
|
+
type RawEdge<D extends RelationTypeDef> = D extends unknown ? D["edge"] : never;
|
|
626
|
+
/** `edgeWhere` is only available when every relation in `via` has a `relationship { … }` model. */
|
|
627
|
+
type EdgeWhereFor<TM extends TypeMap, M extends keyof TM, R extends keyof Relations<TM, M>> = null extends RawEdge<Rel<TM, M, R>> ? never : EdgeWhereInput<RawEdge<Rel<TM, M, R>>>;
|
|
628
|
+
/**
|
|
629
|
+
* Arrow direction of each hop, from the node you step from. Default: the direction declared by
|
|
630
|
+
* each relation's `@relationship(direction: …)`.
|
|
631
|
+
*/
|
|
632
|
+
type TraversalDirection = "out" | "in" | "both";
|
|
633
|
+
type TraverseArgs<TM extends TypeMap, M extends keyof TM, R extends SelfRelations<TM, M>> = {
|
|
634
|
+
/** Start node(s): any filter on `M` (`{ id }`, `{ email }`, …). */
|
|
635
|
+
from: WhereInput<TM, M>;
|
|
636
|
+
/** Relation(s) of `M` to follow; each must lead back to `M`. Several: any of them on each hop. */
|
|
637
|
+
via: R | readonly R[];
|
|
638
|
+
direction?: TraversalDirection;
|
|
639
|
+
/**
|
|
640
|
+
* Hops: `min` (default `1`, `0` includes the start node) to `max` (required, at most the client's
|
|
641
|
+
* `maxTraversalDepth`, default 10).
|
|
642
|
+
*/
|
|
643
|
+
depth: {
|
|
644
|
+
min?: number;
|
|
645
|
+
max: number;
|
|
646
|
+
};
|
|
647
|
+
/** Filter on the reached nodes. */
|
|
648
|
+
where?: WhereInput<TM, M>;
|
|
649
|
+
/** Filter on the properties of every edge of the path. */
|
|
650
|
+
edgeWhere?: EdgeWhereFor<TM, M, NoInfer<R>>;
|
|
651
|
+
/** Return each reached node once (default `true`); `false`: one result per path. */
|
|
652
|
+
distinct?: boolean;
|
|
653
|
+
orderBy?: OrderByInput<TM, M>;
|
|
654
|
+
skip?: number;
|
|
655
|
+
take?: number;
|
|
656
|
+
};
|
|
657
|
+
/** One `traverse` result with `returnPaths: true`. */
|
|
658
|
+
type TraversalResult<TM extends TypeMap, M extends keyof TM, R extends keyof Relations<TM, M>, N> = {
|
|
659
|
+
/** The reached node (honours `select` / `include`). */
|
|
660
|
+
node: N;
|
|
661
|
+
/** How it was reached from a start node (the shortest such path when `distinct`). */
|
|
662
|
+
path: ModelPath<TM, M, R>;
|
|
663
|
+
};
|
|
664
|
+
type TraverseOut<TM extends TypeMap, M extends keyof TM, R extends keyof Relations<TM, M>, N, P> = P extends true ? TraversalResult<TM, M, R, N> : N;
|
|
665
|
+
type ShortestPathArgs<TM extends TypeMap, M extends keyof TM, R extends SelfRelations<TM, M>> = {
|
|
666
|
+
/** Start node(s): any filter on `M`. */
|
|
667
|
+
from: WhereInput<TM, M>;
|
|
668
|
+
/** End node(s): any filter on `M`. A node matching both `from` and `to` gives a zero-hop path. */
|
|
669
|
+
to: WhereInput<TM, M>;
|
|
670
|
+
/** Relation(s) of `M` to follow; each must lead back to `M`. Several: any of them on each hop. */
|
|
671
|
+
via: R | readonly R[];
|
|
672
|
+
direction?: TraversalDirection;
|
|
673
|
+
/** Longest path searched, in hops (required, at most the client's `maxTraversalDepth`). */
|
|
674
|
+
maxDepth: number;
|
|
675
|
+
/** Filter every intermediate node must match (not the start and end nodes). */
|
|
676
|
+
where?: WhereInput<TM, M>;
|
|
677
|
+
/** Filter on the properties of every edge of the path. */
|
|
678
|
+
edgeWhere?: EdgeWhereFor<TM, M, NoInfer<R>>;
|
|
679
|
+
};
|
|
680
|
+
/** A shortest path: its nodes (honouring `select` / `include`) and its typed edges. */
|
|
681
|
+
type ShortestPathResult<TM extends TypeMap, M extends keyof TM, R extends keyof Relations<TM, M>, N> = Path<N, PathEdge<EdgeProps<Rel<TM, M, R>>>>;
|
|
357
682
|
type Sel<TM extends TypeMap, M extends keyof TM> = SelectInput<TM, M> | undefined;
|
|
358
683
|
type Inc<TM extends TypeMap, M extends keyof TM> = IncludeInput<TM, M> | undefined;
|
|
359
684
|
type Out<TM extends TypeMap, M extends keyof TM, S, I> = Payload<TM, M, {
|
|
@@ -378,6 +703,34 @@ type ModelDelegate<TM extends TypeMap, M extends keyof TM> = {
|
|
|
378
703
|
/** Detach-deletes the node and returns it as it was. */
|
|
379
704
|
delete<S extends Sel<TM, M> = undefined, I extends Inc<TM, M> = undefined>(args: DeleteArgs<TM, M> & Projection<S, I>): Promise<Out<TM, M, S, I>>;
|
|
380
705
|
deleteMany(args?: CountArgs<TM, M>): Promise<BatchResult>;
|
|
706
|
+
/**
|
|
707
|
+
* `_count`, `_sum`, `_avg`, `_min` and `_max` over the matching nodes, in one statement.
|
|
708
|
+
* Nulls are ignored; on an empty match counts are `0` and the other aggregates `null`.
|
|
709
|
+
*/
|
|
710
|
+
aggregate<C extends CountSel<TM, M> = undefined, Su extends FieldSel<NumericKeys<TM, M>> = undefined, Av extends FieldSel<NumericKeys<TM, M>> = undefined, Mi extends FieldSel<MinMaxKeys<TM, M>> = undefined, Ma extends FieldSel<MinMaxKeys<TM, M>> = undefined>(args?: AggregateArgs<TM, M> & AggregateProjection<TM, M, C, Su, Av, Mi, Ma>): Promise<AggregateResult<TM, M, C, Su, Av, Mi, Ma>>;
|
|
711
|
+
/**
|
|
712
|
+
* Follow `via` from the `from` node(s) for `depth.min`..`depth.max` hops and return the reached
|
|
713
|
+
* nodes, in one statement (a quantified path pattern, Neo4j 5.9+). `returnPaths: true` returns
|
|
714
|
+
* `{ node, path }` with the typed nodes and edges of the path.
|
|
715
|
+
*/
|
|
716
|
+
traverse<R extends SelfRelations<TM, M>, S extends Sel<TM, M> = undefined, I extends Inc<TM, M> = undefined, P extends boolean = false>(args: TraverseArgs<TM, M, R> & Projection<S, I> & {
|
|
717
|
+
returnPaths?: P;
|
|
718
|
+
}): Promise<TraverseOut<TM, M, R, Out<TM, M, S, I>, P>[]>;
|
|
719
|
+
/**
|
|
720
|
+
* One shortest path from a `from` node to a `to` node along `via`, at most `maxDepth` hops, or
|
|
721
|
+
* `null` (one statement, `SHORTEST 1`, Neo4j 5.21+). With several start or end nodes, the
|
|
722
|
+
* shortest path over every pair.
|
|
723
|
+
*/
|
|
724
|
+
shortestPath<R extends SelfRelations<TM, M>, S extends Sel<TM, M> = undefined, I extends Inc<TM, M> = undefined>(args: ShortestPathArgs<TM, M, R> & Projection<S, I>): Promise<ShortestPathResult<TM, M, R, Out<TM, M, S, I>> | null>;
|
|
725
|
+
/**
|
|
726
|
+
* Every shortest path from a `from` node to a `to` node along `via` (all of the same, minimal
|
|
727
|
+
* length), at most `maxDepth` hops, up to `take` paths (one statement, `ALL SHORTEST`).
|
|
728
|
+
*/
|
|
729
|
+
allShortestPaths<R extends SelfRelations<TM, M>, S extends Sel<TM, M> = undefined, I extends Inc<TM, M> = undefined>(args: ShortestPathArgs<TM, M, R> & Projection<S, I> & {
|
|
730
|
+
take?: number;
|
|
731
|
+
}): Promise<ShortestPathResult<TM, M, R, Out<TM, M, S, I>>[]>;
|
|
732
|
+
/** Group matching nodes by `by` and aggregate each group, in one statement. */
|
|
733
|
+
groupBy<B extends GroupByField<TM, M>, C extends CountSel<TM, M> = undefined, Su extends FieldSel<NumericKeys<TM, M>> = undefined, Av extends FieldSel<NumericKeys<TM, M>> = undefined, Mi extends FieldSel<MinMaxKeys<TM, M>> = undefined, Ma extends FieldSel<MinMaxKeys<TM, M>> = undefined>(args: GroupByArgs<TM, M, B> & AggregateProjection<TM, M, C, Su, Av, Mi, Ma>): Promise<GroupByRow<TM, M, B, C, Su, Av, Mi, Ma>[]>;
|
|
381
734
|
};
|
|
382
735
|
/** Lower-cases the first character: `BlogPost` → `blogPost`. */
|
|
383
736
|
type DelegateKey<M extends string> = Uncapitalize<M>;
|
|
@@ -385,10 +738,19 @@ type ModelDelegates<TM extends TypeMap> = {
|
|
|
385
738
|
[M in keyof TM & string as DelegateKey<M>]: ModelDelegate<TM, M>;
|
|
386
739
|
};
|
|
387
740
|
|
|
388
|
-
/**
|
|
389
|
-
|
|
741
|
+
/**
|
|
742
|
+
* Options for {@link createOrm}: connection options, an existing `neo4j-driver` 5.28+ / 6.x
|
|
743
|
+
* `Driver` (`{ driver }`), or an existing {@link CyphraClient}.
|
|
744
|
+
*/
|
|
745
|
+
type OrmOptions = (CyphraClientOptions | {
|
|
390
746
|
client: CyphraClient;
|
|
391
747
|
debug?: boolean;
|
|
748
|
+
}) & {
|
|
749
|
+
/**
|
|
750
|
+
* Largest `depth.max` a `traverse` may ask for (default 10). Each extra hop can multiply the
|
|
751
|
+
* number of paths Neo4j explores, so keep it as low as your queries allow.
|
|
752
|
+
*/
|
|
753
|
+
maxTraversalDepth?: number;
|
|
392
754
|
};
|
|
393
755
|
type Raw = {
|
|
394
756
|
/**
|
|
@@ -414,7 +776,7 @@ type OrmClient<TM extends TypeMap> = ModelDelegates<TM> & Raw & {
|
|
|
414
776
|
readonly $client: CyphraClient;
|
|
415
777
|
/** The resolved schema the client was built from. */
|
|
416
778
|
readonly $schema: SchemaModel;
|
|
417
|
-
/** Close the driver (only when the client owns it, i.e. it was created from connection options). */
|
|
779
|
+
/** Close the driver (only when the client owns it, i.e. it was created from connection options, not from `{ driver }` or `{ client }`). */
|
|
418
780
|
$disconnect(): Promise<void>;
|
|
419
781
|
};
|
|
420
782
|
/**
|
|
@@ -461,4 +823,4 @@ declare function createCuid(): string;
|
|
|
461
823
|
*/
|
|
462
824
|
declare function toNative(value: unknown): unknown;
|
|
463
825
|
|
|
464
|
-
export { type BatchResult, type CountArgs, type CreateArgs, type CreateInput, type CreateManyArgs, CyphraClient, type CyphraClientOptions, CyphraError, CyphraValidationError, type DelegateKey, type DeleteArgs, type FindManyArgs, type FindUniqueArgs, type IncludeInput, type ModelDelegate, type ModelDelegates, type ModelTypeDef, NotFoundError, type OrderByInput, type OrmClient, type OrmOptions, type OrmTransactionClient, type Payload, type QueryMode, type RelationLoadArgs, type RelationTypeDef, type ScalarFilter, type SelectInput, type SortOrder, type TypeMap, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpsertArgs, type WhereInput, type WhereUniqueInput, createCuid, createOrm, toNative, toPlainRecord, toPlainRecords };
|
|
826
|
+
export { type AggregateArgs, type AggregateFieldsInput, type AggregateResult, type BatchResult, type CountAggregateInput, type CountArgs, type CreateArgs, type CreateInput, type CreateManyArgs, CyphraClient, type CyphraClientOptions, type CyphraConnectionOptions, type CyphraDriverOptions, CyphraError, CyphraValidationError, type DelegateKey, type DeleteArgs, type DriverLike, type EdgeWhereInput, type FindManyArgs, type FindUniqueArgs, type GroupByArgs, type GroupByField, type GroupByKeys, type GroupByOrderByInput, type GroupByRow, type HavingInput, type IncludeInput, type MinMaxKeys, type ModelDelegate, type ModelDelegates, type ModelPath, type ModelTypeDef, NotFoundError, type NumericKeys, type OrderByInput, type OrmClient, type OrmOptions, type OrmTransactionClient, type Path, type PathEdge, type Payload, type QueryMode, type RelationCountInput, type RelationLoadArgs, type RelationTypeDef, type ScalarFilter, type SelectInput, type SelfRelations, type SessionLike, type ShortestPathArgs, type ShortestPathResult, type SortOrder, type ToManyRelations, type TransactionLike, type TraversalDirection, type TraversalResult, type TraverseArgs, type TypeMap, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpsertArgs, type WhereInput, type WhereUniqueInput, createCuid, createOrm, toNative, toPlainRecord, toPlainRecords };
|