@cyphra/runtime 0.5.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/dist/index.d.ts CHANGED
@@ -277,11 +277,19 @@ type WhereUniqueInput<TM extends TypeMap, M extends keyof TM> = RequireAtLeastOn
277
277
  [K in TM[M]["unique"] & keyof Scalars<TM, M>]: NonNullable<Scalars<TM, M>[K]>;
278
278
  }> & WhereInput<TM, M>;
279
279
  type SortOrder = "asc" | "desc";
280
- type OrderByInput<TM extends TypeMap, M extends keyof TM> = {
281
- [K in keyof Scalars<TM, M>]?: SortOrder;
282
- } | readonly {
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> = {
283
286
  [K in keyof Scalars<TM, M>]?: SortOrder;
284
- }[];
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>[];
285
293
  /** Options for loading a relation inside `select` / `include`. */
286
294
  type RelationLoadArgs<TM extends TypeMap, T extends keyof TM> = {
287
295
  where?: WhereInput<TM, T>;
@@ -291,13 +299,30 @@ type RelationLoadArgs<TM extends TypeMap, T extends keyof TM> = {
291
299
  select?: SelectInput<TM, T>;
292
300
  include?: IncludeInput<TM, T>;
293
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
+ };
294
313
  type SelectInput<TM extends TypeMap, M extends keyof TM> = {
295
314
  [K in keyof Scalars<TM, M>]?: boolean;
296
315
  } & {
297
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>;
298
320
  };
299
321
  type IncludeInput<TM extends TypeMap, M extends keyof TM> = {
300
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>;
301
326
  };
302
327
  type EdgePart<D extends RelationTypeDef> = D["edge"] extends Record<string, unknown> ? {
303
328
  $edge: D["edge"];
@@ -306,14 +331,25 @@ type RelationPayload<TM extends TypeMap, D extends RelationTypeDef, A> = D["many
306
331
  type TrueKeys<T> = {
307
332
  [K in keyof T]: T[K] extends false | undefined ? never : K;
308
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;
309
345
  type SelectPayload<TM extends TypeMap, M extends keyof TM, S> = {
310
346
  [K in TrueKeys<S> & keyof Scalars<TM, M>]: Scalars<TM, M>[K];
311
347
  } & {
312
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>;
313
- };
349
+ } & CountPart<TM, M, S>;
314
350
  type IncludePayload<TM extends TypeMap, M extends keyof TM, I> = Scalars<TM, M> & {
315
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>;
316
- };
352
+ } & CountPart<TM, M, I>;
317
353
  /** Result type of a query on model `M` with args `A` (honours `select` / `include`). */
318
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>>;
319
355
  type IsObject<X> = [X] extends [never] ? false : [X] extends [object] ? true : false;
@@ -553,6 +589,96 @@ type GroupByArgs<TM extends TypeMap, M extends keyof TM, B> = {
553
589
  };
554
590
  /** One row of a `groupBy` result. */
555
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>>>>;
556
682
  type Sel<TM extends TypeMap, M extends keyof TM> = SelectInput<TM, M> | undefined;
557
683
  type Inc<TM extends TypeMap, M extends keyof TM> = IncludeInput<TM, M> | undefined;
558
684
  type Out<TM extends TypeMap, M extends keyof TM, S, I> = Payload<TM, M, {
@@ -582,6 +708,27 @@ type ModelDelegate<TM extends TypeMap, M extends keyof TM> = {
582
708
  * Nulls are ignored; on an empty match counts are `0` and the other aggregates `null`.
583
709
  */
584
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>>[]>;
585
732
  /** Group matching nodes by `by` and aggregate each group, in one statement. */
586
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>[]>;
587
734
  };
@@ -595,9 +742,15 @@ type ModelDelegates<TM extends TypeMap> = {
595
742
  * Options for {@link createOrm}: connection options, an existing `neo4j-driver` 5.28+ / 6.x
596
743
  * `Driver` (`{ driver }`), or an existing {@link CyphraClient}.
597
744
  */
598
- type OrmOptions = CyphraClientOptions | {
745
+ type OrmOptions = (CyphraClientOptions | {
599
746
  client: CyphraClient;
600
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;
601
754
  };
602
755
  type Raw = {
603
756
  /**
@@ -670,4 +823,4 @@ declare function createCuid(): string;
670
823
  */
671
824
  declare function toNative(value: unknown): unknown;
672
825
 
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 };
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 };