@cyphra/runtime 0.3.0 → 0.5.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 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 CyphraClientOptions = {
8
- /** Bolt / Neo4j URI, e.g. `neo4j+s://xxx.databases.neo4j.io`. */
9
- uri: string;
10
- user: string;
11
- password: string;
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
- /** Close the driver (call on shutdown). */
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
 
@@ -188,7 +238,15 @@ type ScalarFilter<T> = [NonNullable<T>] extends [readonly (infer E)[]] ? {
188
238
  contains?: string;
189
239
  startsWith?: string;
190
240
  endsWith?: string;
241
+ /**
242
+ * `"insensitive"` compares lower-cased values (`toLower()`) for `equals`, `not`,
243
+ * `in`, `notIn`, `contains`, `startsWith` and `endsWith`. Range filters
244
+ * (`lt`, `gte`, …) stay case-sensitive. Default: `"default"` (case-sensitive).
245
+ */
246
+ mode?: QueryMode;
191
247
  } : unknown));
248
+ /** Case sensitivity of string filters (same values as Prisma's `QueryMode`). */
249
+ type QueryMode = "default" | "insensitive";
192
250
  type RelationFilter<TM extends TypeMap, D extends RelationTypeDef> = D["many"] extends true ? {
193
251
  /** At least one related node matches. */
194
252
  some?: WhereInput<TM, D["target"] & keyof TM>;
@@ -346,6 +404,155 @@ type CountArgs<TM extends TypeMap, M extends keyof TM> = {
346
404
  type BatchResult = {
347
405
  count: number;
348
406
  };
407
+ type ScalarKeys<TM extends TypeMap, M extends keyof TM> = keyof Scalars<TM, M> & string;
408
+ /** Scalar keys whose (non-null) type is `number` (`Int`, `Float`): valid for `_sum` / `_avg`. */
409
+ type NumericKeys<TM extends TypeMap, M extends keyof TM> = {
410
+ [K in ScalarKeys<TM, M>]: NonNullable<Scalars<TM, M>[K]> extends number ? K : never;
411
+ }[ScalarKeys<TM, M>];
412
+ /** Scalar keys of `Int`, `Float`, `String`, `DateTime` and `Date` fields: valid for `_min` / `_max`. */
413
+ type MinMaxKeys<TM extends TypeMap, M extends keyof TM> = {
414
+ [K in ScalarKeys<TM, M>]: NonNullable<Scalars<TM, M>[K]> extends number | string | Date ? K : never;
415
+ }[ScalarKeys<TM, M>];
416
+ /** Rejects keys outside `Allowed` (TypeScript does not check excess keys of inferred generics). */
417
+ type OnlyKeys<T, Allowed extends PropertyKey> = {
418
+ [K in keyof T]: K extends Allowed ? T[K] : never;
419
+ };
420
+ /** `_count: { _all: true, email: true }`: `_all` counts nodes, a field counts non-null values. */
421
+ type CountAggregateInput<TM extends TypeMap, M extends keyof TM> = {
422
+ [K in ScalarKeys<TM, M> | "_all"]?: boolean;
423
+ };
424
+ type AggregateFieldsInput<K extends PropertyKey> = {
425
+ [P in K]?: boolean;
426
+ };
427
+ type CountSel<TM extends TypeMap, M extends keyof TM> = true | CountAggregateInput<TM, M> | undefined;
428
+ type FieldSel<K extends PropertyKey> = AggregateFieldsInput<K> | undefined;
429
+ /**
430
+ * The aggregate selections, each captured as its own type parameter (like `select` / `include`)
431
+ * so the result type follows them exactly while the other arguments keep excess-property checks.
432
+ */
433
+ type AggregateProjection<TM extends TypeMap, M extends keyof TM, C, Su, Av, Mi, Ma> = {
434
+ /** `true`: number of nodes. An object: `_all` (nodes) and/or fields (non-null values). */
435
+ _count?: C extends object ? C & OnlyKeys<C, ScalarKeys<TM, M> | "_all"> : C;
436
+ /** Sum of non-null values (`Int` / `Float`); `null` when there are none. */
437
+ _sum?: Su & OnlyKeys<Su, NumericKeys<TM, M>>;
438
+ /** Mean of non-null values (`Int` / `Float`); `null` when there are none. */
439
+ _avg?: Av & OnlyKeys<Av, NumericKeys<TM, M>>;
440
+ /** Smallest non-null value (`Int`, `Float`, `String`, `DateTime`, `Date`). */
441
+ _min?: Mi & OnlyKeys<Mi, MinMaxKeys<TM, M>>;
442
+ /** Largest non-null value (`Int`, `Float`, `String`, `DateTime`, `Date`). */
443
+ _max?: Ma & OnlyKeys<Ma, MinMaxKeys<TM, M>>;
444
+ };
445
+ type CountOut<C> = C extends true ? number : {
446
+ [K in TrueKeys<C>]: number;
447
+ };
448
+ type AggOut<Sel, V> = {
449
+ [K in TrueKeys<Sel>]: V;
450
+ };
451
+ type ValueOut<TM extends TypeMap, M extends keyof TM, Sel> = {
452
+ [K in TrueKeys<Sel> & keyof Scalars<TM, M>]: NonNullable<Scalars<TM, M>[K]> | null;
453
+ };
454
+ /** Result of the aggregate part (`_count`, `_sum`, …) of `aggregate` / `groupBy`. */
455
+ type AggregateResult<TM extends TypeMap, M extends keyof TM, C, Su, Av, Mi, Ma> = Simplify<([C] extends [undefined] ? unknown : {
456
+ _count: CountOut<Exclude<C, undefined>>;
457
+ }) & ([Su] extends [undefined] ? unknown : {
458
+ _sum: AggOut<Su, number | null>;
459
+ }) & ([Av] extends [undefined] ? unknown : {
460
+ _avg: AggOut<Av, number | null>;
461
+ }) & ([Mi] extends [undefined] ? unknown : {
462
+ _min: ValueOut<TM, M, Mi>;
463
+ }) & ([Ma] extends [undefined] ? unknown : {
464
+ _max: ValueOut<TM, M, Ma>;
465
+ })>;
466
+ type AggregateArgs<TM extends TypeMap, M extends keyof TM> = {
467
+ where?: WhereInput<TM, M>;
468
+ /** With `skip` / `take`: aggregate over this window of matching nodes only. */
469
+ orderBy?: OrderByInput<TM, M>;
470
+ skip?: number;
471
+ take?: number;
472
+ };
473
+ type ToOneRelations<TM extends TypeMap, M extends keyof TM> = {
474
+ [R in keyof Relations<TM, M> & string]: Rel<TM, M, R>["many"] extends true ? never : R;
475
+ }[keyof Relations<TM, M> & string];
476
+ /**
477
+ * A field `groupBy` can group on: a scalar of the model, or `"relation.field"` for a scalar of a
478
+ * to-one related node (e.g. `"author.name"`).
479
+ */
480
+ type GroupByField<TM extends TypeMap, M extends keyof TM> = ScalarKeys<TM, M> | {
481
+ [R in ToOneRelations<TM, M>]: `${R}.${keyof Scalars<TM, Target<TM, M, R>> & string}`;
482
+ }[ToOneRelations<TM, M>];
483
+ type ByScalar<B> = B extends `${string}.${string}` ? never : B;
484
+ type ByRelation<B> = B extends `${infer R}.${string}` ? R : never;
485
+ type ByRelField<B, R extends string> = B extends `${R}.${infer F}` ? F : never;
486
+ /** The `by` part of one `groupBy` row: `{ status, author: { name } }`. */
487
+ type GroupByKeys<TM extends TypeMap, M extends keyof TM, B> = {
488
+ [K in ByScalar<B> & keyof Scalars<TM, M>]: Scalars<TM, M>[K];
489
+ } & {
490
+ [R in ByRelation<B> & keyof Relations<TM, M>]: {
491
+ [F in ByRelField<B, R & string> & keyof Scalars<TM, Target<TM, M, R>>]: Scalars<TM, Target<TM, M, R>>[F] | null;
492
+ };
493
+ };
494
+ type FilterObject<T> = Exclude<ScalarFilter<T>, T>;
495
+ /** Filters on one aggregate of field `K`, for `having`. */
496
+ type HavingAggregates<TM extends TypeMap, M extends keyof TM, K> = {
497
+ _count?: ScalarFilter<number>;
498
+ } & (K extends NumericKeys<TM, M> ? {
499
+ _sum?: ScalarFilter<number | null>;
500
+ _avg?: ScalarFilter<number | null>;
501
+ } : unknown) & (K extends MinMaxKeys<TM, M> ? {
502
+ _min?: ScalarFilter<NonNullable<Scalars<TM, M>[K & keyof Scalars<TM, M>]> | null>;
503
+ _max?: ScalarFilter<NonNullable<Scalars<TM, M>[K & keyof Scalars<TM, M>]> | null>;
504
+ } : unknown);
505
+ /**
506
+ * `having` on a `groupBy`: aggregates of any scalar (`{ views: { _avg: { gt: 10 } } }`), and plain
507
+ * filters on the fields listed in `by` (`{ status: "draft" }`, `{ author: { name: { not: null } } }`).
508
+ */
509
+ type HavingInput<TM extends TypeMap, M extends keyof TM, B> = {
510
+ [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>;
511
+ } & {
512
+ [R in ByRelation<B> & keyof Relations<TM, M>]?: {
513
+ [F in ByRelField<B, R & string> & keyof Scalars<TM, Target<TM, M, R>>]?: ScalarFilter<Scalars<TM, Target<TM, M, R>>[F]>;
514
+ };
515
+ } & {
516
+ AND?: HavingInput<TM, M, B> | readonly HavingInput<TM, M, B>[];
517
+ OR?: readonly HavingInput<TM, M, B>[];
518
+ NOT?: HavingInput<TM, M, B> | readonly HavingInput<TM, M, B>[];
519
+ };
520
+ type GroupByOrderItem<TM extends TypeMap, M extends keyof TM, B> = {
521
+ [K in ByScalar<B> & ScalarKeys<TM, M>]?: SortOrder;
522
+ } & {
523
+ [R in ByRelation<B> & keyof Relations<TM, M>]?: {
524
+ [F in ByRelField<B, R & string>]?: SortOrder;
525
+ };
526
+ } & {
527
+ _count?: {
528
+ [K in ScalarKeys<TM, M> | "_all"]?: SortOrder;
529
+ };
530
+ _sum?: {
531
+ [K in NumericKeys<TM, M>]?: SortOrder;
532
+ };
533
+ _avg?: {
534
+ [K in NumericKeys<TM, M>]?: SortOrder;
535
+ };
536
+ _min?: {
537
+ [K in MinMaxKeys<TM, M>]?: SortOrder;
538
+ };
539
+ _max?: {
540
+ [K in MinMaxKeys<TM, M>]?: SortOrder;
541
+ };
542
+ };
543
+ /** `orderBy` on a `groupBy`: fields listed in `by`, or aggregates (`{ _count: { id: "desc" } }`). */
544
+ type GroupByOrderByInput<TM extends TypeMap, M extends keyof TM, B> = GroupByOrderItem<TM, M, B> | readonly GroupByOrderItem<TM, M, B>[];
545
+ type GroupByArgs<TM extends TypeMap, M extends keyof TM, B> = {
546
+ /** Fields to group on: `"status"`, `["status", "author.name"]`. */
547
+ by: B | readonly B[];
548
+ where?: WhereInput<TM, M>;
549
+ having?: HavingInput<TM, M, NoInfer<B>>;
550
+ orderBy?: GroupByOrderByInput<TM, M, NoInfer<B>>;
551
+ skip?: number;
552
+ take?: number;
553
+ };
554
+ /** One row of a `groupBy` result. */
555
+ 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>>;
349
556
  type Sel<TM extends TypeMap, M extends keyof TM> = SelectInput<TM, M> | undefined;
350
557
  type Inc<TM extends TypeMap, M extends keyof TM> = IncludeInput<TM, M> | undefined;
351
558
  type Out<TM extends TypeMap, M extends keyof TM, S, I> = Payload<TM, M, {
@@ -370,6 +577,13 @@ type ModelDelegate<TM extends TypeMap, M extends keyof TM> = {
370
577
  /** Detach-deletes the node and returns it as it was. */
371
578
  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>>;
372
579
  deleteMany(args?: CountArgs<TM, M>): Promise<BatchResult>;
580
+ /**
581
+ * `_count`, `_sum`, `_avg`, `_min` and `_max` over the matching nodes, in one statement.
582
+ * Nulls are ignored; on an empty match counts are `0` and the other aggregates `null`.
583
+ */
584
+ 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>>;
585
+ /** Group matching nodes by `by` and aggregate each group, in one statement. */
586
+ 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>[]>;
373
587
  };
374
588
  /** Lower-cases the first character: `BlogPost` → `blogPost`. */
375
589
  type DelegateKey<M extends string> = Uncapitalize<M>;
@@ -377,7 +591,10 @@ type ModelDelegates<TM extends TypeMap> = {
377
591
  [M in keyof TM & string as DelegateKey<M>]: ModelDelegate<TM, M>;
378
592
  };
379
593
 
380
- /** Options for {@link createOrm}: connection options, or an existing {@link CyphraClient}. */
594
+ /**
595
+ * Options for {@link createOrm}: connection options, an existing `neo4j-driver` 5.28+ / 6.x
596
+ * `Driver` (`{ driver }`), or an existing {@link CyphraClient}.
597
+ */
381
598
  type OrmOptions = CyphraClientOptions | {
382
599
  client: CyphraClient;
383
600
  debug?: boolean;
@@ -406,7 +623,7 @@ type OrmClient<TM extends TypeMap> = ModelDelegates<TM> & Raw & {
406
623
  readonly $client: CyphraClient;
407
624
  /** The resolved schema the client was built from. */
408
625
  readonly $schema: SchemaModel;
409
- /** Close the driver (only when the client owns it, i.e. it was created from connection options). */
626
+ /** Close the driver (only when the client owns it, i.e. it was created from connection options, not from `{ driver }` or `{ client }`). */
410
627
  $disconnect(): Promise<void>;
411
628
  };
412
629
  /**
@@ -453,4 +670,4 @@ declare function createCuid(): string;
453
670
  */
454
671
  declare function toNative(value: unknown): unknown;
455
672
 
456
- 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 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 };
673
+ 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 FindManyArgs, type FindUniqueArgs, type GroupByArgs, type GroupByField, type GroupByKeys, type GroupByOrderByInput, type GroupByRow, type HavingInput, type IncludeInput, type MinMaxKeys, type ModelDelegate, type ModelDelegates, type ModelTypeDef, NotFoundError, type NumericKeys, type OrderByInput, type OrmClient, type OrmOptions, type OrmTransactionClient, type Payload, type QueryMode, type RelationLoadArgs, type RelationTypeDef, type ScalarFilter, type SelectInput, type SessionLike, type SortOrder, type TransactionLike, type TypeMap, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpsertArgs, type WhereInput, type WhereUniqueInput, createCuid, createOrm, toNative, toPlainRecord, toPlainRecords };