@cyphra/runtime 0.5.0 → 0.7.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
@@ -203,6 +203,12 @@ type ModelTypeDef = {
203
203
  /** `@id` / `@unique` keys usable in `findUnique`, `connect`, … */
204
204
  readonly unique: string;
205
205
  readonly relations: Record<string, RelationTypeDef>;
206
+ /** `Vector(N)` scalar keys (absent when the model has none). */
207
+ readonly vectors?: string;
208
+ /** `Vector(N)` keys with a `@vectorIndex`: the fields `findSimilar` can search. */
209
+ readonly vectorIndexes?: string;
210
+ /** Names of the model's `@@fulltext` indexes: what `search` can query (absent when none). */
211
+ readonly fulltextIndexes?: string;
206
212
  };
207
213
  type TypeMap = Record<string, ModelTypeDef>;
208
214
  type Scalars<TM extends TypeMap, M extends keyof TM> = TM[M]["scalars"];
@@ -212,6 +218,18 @@ type Target<TM extends TypeMap, M extends keyof TM, R extends keyof Relations<TM
212
218
  type Simplify<T> = {
213
219
  [K in keyof T]: T[K];
214
220
  } & {};
221
+ /** `Vector(N)` scalar keys of model `M`. */
222
+ type VectorKeys<TM extends TypeMap, M extends keyof TM> = TM[M] extends {
223
+ vectors: infer V extends string;
224
+ } ? V : never;
225
+ /** `Vector(N)` keys of model `M` with a `@vectorIndex` (what `findSimilar` searches). */
226
+ type VectorIndexKeys<TM extends TypeMap, M extends keyof TM> = TM[M] extends {
227
+ vectorIndexes: infer V extends string;
228
+ } ? V : never;
229
+ /** Names of the `@@fulltext` indexes of model `M` (what `search` queries). */
230
+ type FulltextIndexNames<TM extends TypeMap, M extends keyof TM> = TM[M] extends {
231
+ fulltextIndexes: infer V extends string;
232
+ } ? V : never;
215
233
  /** Types with `lt` / `lte` / `gt` / `gte` (strings compare lexicographically, by code point). */
216
234
  type Comparable = number | string | Date;
217
235
  /** Filter on one scalar field. A bare value means `equals`; `null` means "property absent". */
@@ -260,8 +278,13 @@ type RelationFilter<TM extends TypeMap, D extends RelationTypeDef> = D["many"] e
260
278
  /** No related node matching this (`null`: a related node exists). */
261
279
  isNot?: WhereInput<TM, D["target"] & keyof TM> | null;
262
280
  };
281
+ /** Vector fields only filter on presence (search them with `findSimilar`). */
282
+ type VectorFilter = null | {
283
+ equals?: null;
284
+ not?: null;
285
+ };
263
286
  type WhereInput<TM extends TypeMap, M extends keyof TM> = {
264
- [K in keyof Scalars<TM, M>]?: ScalarFilter<Scalars<TM, M>[K]>;
287
+ [K in keyof Scalars<TM, M>]?: K extends VectorKeys<TM, M> ? VectorFilter : ScalarFilter<Scalars<TM, M>[K]>;
265
288
  } & {
266
289
  [R in keyof Relations<TM, M>]?: RelationFilter<TM, Rel<TM, M, R>>;
267
290
  } & {
@@ -277,11 +300,19 @@ type WhereUniqueInput<TM extends TypeMap, M extends keyof TM> = RequireAtLeastOn
277
300
  [K in TM[M]["unique"] & keyof Scalars<TM, M>]: NonNullable<Scalars<TM, M>[K]>;
278
301
  }> & WhereInput<TM, M>;
279
302
  type SortOrder = "asc" | "desc";
280
- type OrderByInput<TM extends TypeMap, M extends keyof TM> = {
281
- [K in keyof Scalars<TM, M>]?: SortOrder;
282
- } | readonly {
283
- [K in keyof Scalars<TM, M>]?: SortOrder;
284
- }[];
303
+ /** Keys of the to-many relations of model `M` (the ones `_count` can count). */
304
+ type ToManyRelations<TM extends TypeMap, M extends keyof TM> = {
305
+ [R in keyof Relations<TM, M> & string]: Rel<TM, M, R>["many"] extends true ? R : never;
306
+ }[keyof Relations<TM, M> & string];
307
+ /** One `orderBy` entry: scalars, or a to-many relation by its count (`{ posts: { _count: "desc" } }`). */
308
+ type OrderByItem<TM extends TypeMap, M extends keyof TM> = {
309
+ [K in Exclude<keyof Scalars<TM, M>, VectorKeys<TM, M>>]?: SortOrder;
310
+ } & {
311
+ [R in ToManyRelations<TM, M>]?: {
312
+ _count?: SortOrder;
313
+ };
314
+ };
315
+ type OrderByInput<TM extends TypeMap, M extends keyof TM> = OrderByItem<TM, M> | readonly OrderByItem<TM, M>[];
285
316
  /** Options for loading a relation inside `select` / `include`. */
286
317
  type RelationLoadArgs<TM extends TypeMap, T extends keyof TM> = {
287
318
  where?: WhereInput<TM, T>;
@@ -291,13 +322,30 @@ type RelationLoadArgs<TM extends TypeMap, T extends keyof TM> = {
291
322
  select?: SelectInput<TM, T>;
292
323
  include?: IncludeInput<TM, T>;
293
324
  };
325
+ /**
326
+ * `_count` in `select` / `include`: `true` counts every to-many relation;
327
+ * `{ select: { posts: true, comments: { where } } }` counts the listed ones (optionally filtered).
328
+ */
329
+ type RelationCountInput<TM extends TypeMap, M extends keyof TM> = boolean | {
330
+ select: {
331
+ [R in keyof Relations<TM, M>]?: R extends ToManyRelations<TM, M> ? boolean | {
332
+ where?: WhereInput<TM, Target<TM, M, R>>;
333
+ } : never;
334
+ };
335
+ };
294
336
  type SelectInput<TM extends TypeMap, M extends keyof TM> = {
295
337
  [K in keyof Scalars<TM, M>]?: boolean;
296
338
  } & {
297
339
  [R in keyof Relations<TM, M>]?: boolean | RelationLoadArgs<TM, Target<TM, M, R>>;
340
+ } & {
341
+ /** Number of related nodes per to-many relation. */
342
+ _count?: RelationCountInput<TM, M>;
298
343
  };
299
344
  type IncludeInput<TM extends TypeMap, M extends keyof TM> = {
300
345
  [R in keyof Relations<TM, M>]?: boolean | RelationLoadArgs<TM, Target<TM, M, R>>;
346
+ } & {
347
+ /** Number of related nodes per to-many relation. */
348
+ _count?: RelationCountInput<TM, M>;
301
349
  };
302
350
  type EdgePart<D extends RelationTypeDef> = D["edge"] extends Record<string, unknown> ? {
303
351
  $edge: D["edge"];
@@ -306,14 +354,25 @@ type RelationPayload<TM extends TypeMap, D extends RelationTypeDef, A> = D["many
306
354
  type TrueKeys<T> = {
307
355
  [K in keyof T]: T[K] extends false | undefined ? never : K;
308
356
  }[keyof T];
357
+ /** `{ posts: number, … }` for a `_count` selection `C`. */
358
+ type RelationCountPayload<TM extends TypeMap, M extends keyof TM, C> = C extends true ? {
359
+ [R in ToManyRelations<TM, M>]: number;
360
+ } : C extends {
361
+ select: infer X;
362
+ } ? {
363
+ [R in TrueKeys<X> & ToManyRelations<TM, M>]: number;
364
+ } : never;
365
+ type CountPart<TM extends TypeMap, M extends keyof TM, A> = "_count" extends TrueKeys<A> ? {
366
+ _count: Simplify<RelationCountPayload<TM, M, A["_count" & keyof A]>>;
367
+ } : unknown;
309
368
  type SelectPayload<TM extends TypeMap, M extends keyof TM, S> = {
310
369
  [K in TrueKeys<S> & keyof Scalars<TM, M>]: Scalars<TM, M>[K];
311
370
  } & {
312
371
  [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
- };
372
+ } & CountPart<TM, M, S>;
314
373
  type IncludePayload<TM extends TypeMap, M extends keyof TM, I> = Scalars<TM, M> & {
315
374
  [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
- };
375
+ } & CountPart<TM, M, I>;
317
376
  /** Result type of a query on model `M` with args `A` (honours `select` / `include`). */
318
377
  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
378
  type IsObject<X> = [X] extends [never] ? false : [X] extends [object] ? true : false;
@@ -553,6 +612,172 @@ type GroupByArgs<TM extends TypeMap, M extends keyof TM, B> = {
553
612
  };
554
613
  /** One row of a `groupBy` result. */
555
614
  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>>;
615
+ /** Edge properties of a relation: its `relationship { … }` model, or `{}` when the edge is untyped. */
616
+ type EdgeProps<D extends RelationTypeDef> = D extends unknown ? D["edge"] extends Record<string, unknown> ? D["edge"] : Record<string, never> : never;
617
+ /** One relationship of a {@link Path}: `edges[i]` joins `nodes[i]` and `nodes[i + 1]`. */
618
+ type PathEdge<P = Record<string, unknown>> = {
619
+ /** Neo4j relationship type, e.g. `"FOLLOWS"`. */
620
+ type: string;
621
+ /** `"out"`: the edge points from `nodes[i]` to `nodes[i + 1]`; `"in"`: the other way round. */
622
+ direction: "out" | "in";
623
+ /** Edge properties, typed from the `relationship { … }` model (`{}` for an untyped edge). */
624
+ properties: P;
625
+ };
626
+ /**
627
+ * A path through the graph: `nodes[0] -edges[0]- nodes[1] -edges[1]- …`. `edges.length` is the
628
+ * number of hops and `nodes.length` is always `edges.length + 1`. Nodes carry their scalar fields.
629
+ */
630
+ type Path<N = Record<string, unknown>, E = PathEdge> = {
631
+ nodes: N[];
632
+ edges: E[];
633
+ };
634
+ /** A {@link Path} of `M` nodes joined by edges of the relations `R` of `M`. */
635
+ 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>>>>;
636
+ /** Relations of `M` that lead back to `M` (e.g. `User.following`): the ones a traversal repeats. */
637
+ type SelfRelations<TM extends TypeMap, M extends keyof TM> = {
638
+ [R in keyof Relations<TM, M> & string]: [Rel<TM, M, R>["target"]] extends [M] ? R : never;
639
+ }[keyof Relations<TM, M> & string];
640
+ /** Filter on edge properties: scalar filters, `AND`, `OR`, `NOT`. */
641
+ type EdgeWhereInput<E> = {
642
+ [K in keyof E]?: ScalarFilter<E[K]>;
643
+ } & {
644
+ AND?: EdgeWhereInput<E> | readonly EdgeWhereInput<E>[];
645
+ OR?: readonly EdgeWhereInput<E>[];
646
+ NOT?: EdgeWhereInput<E> | readonly EdgeWhereInput<E>[];
647
+ };
648
+ type RawEdge<D extends RelationTypeDef> = D extends unknown ? D["edge"] : never;
649
+ /** `edgeWhere` is only available when every relation in `via` has a `relationship { … }` model. */
650
+ 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>>>;
651
+ /**
652
+ * Arrow direction of each hop, from the node you step from. Default: the direction declared by
653
+ * each relation's `@relationship(direction: …)`.
654
+ */
655
+ type TraversalDirection = "out" | "in" | "both";
656
+ type TraverseArgs<TM extends TypeMap, M extends keyof TM, R extends SelfRelations<TM, M>> = {
657
+ /** Start node(s): any filter on `M` (`{ id }`, `{ email }`, …). */
658
+ from: WhereInput<TM, M>;
659
+ /** Relation(s) of `M` to follow; each must lead back to `M`. Several: any of them on each hop. */
660
+ via: R | readonly R[];
661
+ direction?: TraversalDirection;
662
+ /**
663
+ * Hops: `min` (default `1`, `0` includes the start node) to `max` (required, at most the client's
664
+ * `maxTraversalDepth`, default 10).
665
+ */
666
+ depth: {
667
+ min?: number;
668
+ max: number;
669
+ };
670
+ /** Filter on the reached nodes. */
671
+ where?: WhereInput<TM, M>;
672
+ /** Filter on the properties of every edge of the path. */
673
+ edgeWhere?: EdgeWhereFor<TM, M, NoInfer<R>>;
674
+ /** Return each reached node once (default `true`); `false`: one result per path. */
675
+ distinct?: boolean;
676
+ orderBy?: OrderByInput<TM, M>;
677
+ skip?: number;
678
+ take?: number;
679
+ };
680
+ /** One `traverse` result with `returnPaths: true`. */
681
+ type TraversalResult<TM extends TypeMap, M extends keyof TM, R extends keyof Relations<TM, M>, N> = {
682
+ /** The reached node (honours `select` / `include`). */
683
+ node: N;
684
+ /** How it was reached from a start node (the shortest such path when `distinct`). */
685
+ path: ModelPath<TM, M, R>;
686
+ };
687
+ 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;
688
+ type ShortestPathArgs<TM extends TypeMap, M extends keyof TM, R extends SelfRelations<TM, M>> = {
689
+ /** Start node(s): any filter on `M`. */
690
+ from: WhereInput<TM, M>;
691
+ /** End node(s): any filter on `M`. A node matching both `from` and `to` gives a zero-hop path. */
692
+ to: WhereInput<TM, M>;
693
+ /** Relation(s) of `M` to follow; each must lead back to `M`. Several: any of them on each hop. */
694
+ via: R | readonly R[];
695
+ direction?: TraversalDirection;
696
+ /** Longest path searched, in hops (required, at most the client's `maxTraversalDepth`). */
697
+ maxDepth: number;
698
+ /** Filter every intermediate node must match (not the start and end nodes). */
699
+ where?: WhereInput<TM, M>;
700
+ /** Filter on the properties of every edge of the path. */
701
+ edgeWhere?: EdgeWhereFor<TM, M, NoInfer<R>>;
702
+ };
703
+ /** A shortest path: its nodes (honouring `select` / `include`) and its typed edges. */
704
+ type ShortestPathResult<TM extends TypeMap, M extends keyof TM, R extends keyof Relations<TM, M>, N> = Path<N, PathEdge<EdgeProps<Rel<TM, M, R>>>>;
705
+ type FindSimilarArgs<TM extends TypeMap, M extends keyof TM> = {
706
+ /** The `Vector(N)` field to search; it must have a `@vectorIndex`. */
707
+ field: VectorIndexKeys<TM, M>;
708
+ /** Query embedding. Its length must equal the field's dimensions (checked at runtime). */
709
+ vector: readonly number[];
710
+ /** Number of results (best first). */
711
+ k: number;
712
+ /**
713
+ * Filter on the results. The vector index has no filter argument, so `findSimilar` asks it for
714
+ * `candidates` neighbours, filters them, and widens the search (×4) until `k` rows match or the
715
+ * index is exhausted. Use `exact: true` when the filter is selective.
716
+ */
717
+ where?: WhereInput<TM, M>;
718
+ /** Drop results scoring below this (scores are in `[0, 1]`, higher is more similar). */
719
+ minScore?: number;
720
+ /**
721
+ * Neighbours asked from the index on the first attempt (at least `k`; default `k`, or
722
+ * `max(10 × k, 100)` with a `where`). More candidates improve the recall of the approximate search.
723
+ */
724
+ candidates?: number;
725
+ /** Upper bound on the candidates of a filtered search (default: no bound). */
726
+ maxCandidates?: number;
727
+ /**
728
+ * Skip the index: score every node matching `where` with `vector.similarity.*` (exact results,
729
+ * Neo4j 5.18+). Fast when `where` narrows the search to a few thousand nodes.
730
+ */
731
+ exact?: boolean;
732
+ };
733
+ /** A `findSimilar` result: the node (honouring `select` / `include`) and its similarity score. */
734
+ type SimilarResult<N> = Simplify<N & {
735
+ $score: number;
736
+ }>;
737
+ type VectorDelegate<TM extends TypeMap, M extends keyof TM> = [VectorIndexKeys<TM, M>] extends [
738
+ never
739
+ ] ? unknown : {
740
+ /**
741
+ * The `k` nodes whose `field` is most similar to `vector`, best first, each with its
742
+ * `$score`, through the field's vector index (`db.index.vector.queryNodes`, Neo4j 5.15+).
743
+ */
744
+ findSimilar<S extends Sel<TM, M> = undefined, I extends Inc<TM, M> = undefined>(args: FindSimilarArgs<TM, M> & Projection<S, I>): Promise<SimilarResult<Out<TM, M, S, I>>[]>;
745
+ };
746
+ /**
747
+ * How `search` reads `query`: `"lucene"` passes it through as Lucene query syntax (`title:graph*`,
748
+ * `"exact phrase"`, `a AND NOT b`, `fuzzy~`); `"terms"` escapes it and matches any of its words
749
+ * (ranked by relevance); `"phrase"` escapes it and matches the words in that order.
750
+ */
751
+ type SearchMode = "lucene" | "terms" | "phrase";
752
+ type SearchArgs<TM extends TypeMap, M extends keyof TM> = {
753
+ /** The `@@fulltext` index to query (one of this model's index names). */
754
+ index: FulltextIndexNames<TM, M>;
755
+ /** The search text. A blank query matches nothing (`[]`). */
756
+ query: string;
757
+ /** How to read `query` (default `"lucene"`: Lucene query syntax, passed through). */
758
+ mode?: SearchMode;
759
+ /** Filter on the hits, applied in the same statement before `skip` / `take`. */
760
+ where?: WhereInput<TM, M>;
761
+ /** Drop hits scoring below this (Lucene scores: positive, unbounded, per-query). */
762
+ minScore?: number;
763
+ /** Hits to skip, after filtering and ranking. */
764
+ skip?: number;
765
+ /** Maximum number of hits (default: all of them). */
766
+ take?: number;
767
+ };
768
+ /** A `search` result: the node (honouring `select` / `include`) and its relevance score. */
769
+ type SearchResult<N> = Simplify<N & {
770
+ $score: number;
771
+ }>;
772
+ type FulltextDelegate<TM extends TypeMap, M extends keyof TM> = [
773
+ FulltextIndexNames<TM, M>
774
+ ] extends [never] ? unknown : {
775
+ /**
776
+ * Nodes matching a full-text `query` on one of the model's `@@fulltext` indexes, best first,
777
+ * each with its `$score` (`db.index.fulltext.queryNodes`).
778
+ */
779
+ search<S extends Sel<TM, M> = undefined, I extends Inc<TM, M> = undefined>(args: SearchArgs<TM, M> & Projection<S, I>): Promise<SearchResult<Out<TM, M, S, I>>[]>;
780
+ };
556
781
  type Sel<TM extends TypeMap, M extends keyof TM> = SelectInput<TM, M> | undefined;
557
782
  type Inc<TM extends TypeMap, M extends keyof TM> = IncludeInput<TM, M> | undefined;
558
783
  type Out<TM extends TypeMap, M extends keyof TM, S, I> = Payload<TM, M, {
@@ -560,7 +785,8 @@ type Out<TM extends TypeMap, M extends keyof TM, S, I> = Payload<TM, M, {
560
785
  include: I;
561
786
  }>;
562
787
  /** Operations available on `db.<model>`. */
563
- type ModelDelegate<TM extends TypeMap, M extends keyof TM> = {
788
+ type ModelDelegate<TM extends TypeMap, M extends keyof TM> = BaseModelDelegate<TM, M> & VectorDelegate<TM, M> & FulltextDelegate<TM, M>;
789
+ type BaseModelDelegate<TM extends TypeMap, M extends keyof TM> = {
564
790
  findMany<S extends Sel<TM, M> = undefined, I extends Inc<TM, M> = undefined>(args?: FindManyArgs<TM, M> & Projection<S, I>): Promise<Out<TM, M, S, I>[]>;
565
791
  findFirst<S extends Sel<TM, M> = undefined, I extends Inc<TM, M> = undefined>(args?: FindManyArgs<TM, M> & Projection<S, I>): Promise<Out<TM, M, S, I> | null>;
566
792
  /** `null` when no node matches. */
@@ -582,6 +808,27 @@ type ModelDelegate<TM extends TypeMap, M extends keyof TM> = {
582
808
  * Nulls are ignored; on an empty match counts are `0` and the other aggregates `null`.
583
809
  */
584
810
  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>>;
811
+ /**
812
+ * Follow `via` from the `from` node(s) for `depth.min`..`depth.max` hops and return the reached
813
+ * nodes, in one statement (a quantified path pattern, Neo4j 5.9+). `returnPaths: true` returns
814
+ * `{ node, path }` with the typed nodes and edges of the path.
815
+ */
816
+ 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> & {
817
+ returnPaths?: P;
818
+ }): Promise<TraverseOut<TM, M, R, Out<TM, M, S, I>, P>[]>;
819
+ /**
820
+ * One shortest path from a `from` node to a `to` node along `via`, at most `maxDepth` hops, or
821
+ * `null` (one statement, `SHORTEST 1`, Neo4j 5.21+). With several start or end nodes, the
822
+ * shortest path over every pair.
823
+ */
824
+ 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>;
825
+ /**
826
+ * Every shortest path from a `from` node to a `to` node along `via` (all of the same, minimal
827
+ * length), at most `maxDepth` hops, up to `take` paths (one statement, `ALL SHORTEST`).
828
+ */
829
+ 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> & {
830
+ take?: number;
831
+ }): Promise<ShortestPathResult<TM, M, R, Out<TM, M, S, I>>[]>;
585
832
  /** Group matching nodes by `by` and aggregate each group, in one statement. */
586
833
  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
834
  };
@@ -595,9 +842,15 @@ type ModelDelegates<TM extends TypeMap> = {
595
842
  * Options for {@link createOrm}: connection options, an existing `neo4j-driver` 5.28+ / 6.x
596
843
  * `Driver` (`{ driver }`), or an existing {@link CyphraClient}.
597
844
  */
598
- type OrmOptions = CyphraClientOptions | {
845
+ type OrmOptions = (CyphraClientOptions | {
599
846
  client: CyphraClient;
600
847
  debug?: boolean;
848
+ }) & {
849
+ /**
850
+ * Largest `depth.max` a `traverse` may ask for (default 10). Each extra hop can multiply the
851
+ * number of paths Neo4j explores, so keep it as low as your queries allow.
852
+ */
853
+ maxTraversalDepth?: number;
601
854
  };
602
855
  type Raw = {
603
856
  /**
@@ -664,10 +917,37 @@ declare class NotFoundError extends CyphraError {
664
917
  /** Collision-resistant, URL-safe id (cuid2-style: a letter followed by 23 base-36 chars). */
665
918
  declare function createCuid(): string;
666
919
 
920
+ /**
921
+ * `search`: full-text search on a node model through one of its `@@fulltext` indexes.
922
+ *
923
+ * One read-only statement: `db.index.fulltext.queryNodes(index, query)` returns every node of the
924
+ * index matching the Lucene query, with its relevance score; `where` and `minScore` filter those
925
+ * hits in the same statement, then the rows are ranked by score (best first) and `skip` / `take`
926
+ * page through them. Unlike a vector search there is no top-k cut-off before the filter, so a
927
+ * filtered search never comes back short.
928
+ *
929
+ * Scores are Lucene's (BM25): positive, unbounded, and only comparable within one query.
930
+ *
931
+ * @packageDocumentation
932
+ */
933
+
934
+ /**
935
+ * Escape `text` for Lucene's query syntax (what `db.index.fulltext.queryNodes` parses): every
936
+ * special character (`+ - && || ! ( ) { } [ ] ^ " ~ * ? : \ /`) and the `AND` / `OR` / `NOT`
937
+ * operators are backslash-escaped, so user input is searched as plain words.
938
+ *
939
+ * @example
940
+ * ```ts
941
+ * escapeLucene('C++ (beta) AND "x"'); // 'C\\+\\+ \\(beta\\) \\AND \\"x\\"'
942
+ * await db.post.search({ index: "postSearch", query: `title:${escapeLucene(input)}~` });
943
+ * ```
944
+ */
945
+ declare function escapeLucene(text: string): string;
946
+
667
947
  /**
668
948
  * Best-effort conversion of arbitrary driver values to plain JS: integers → number,
669
949
  * temporal values → `Date`, nodes/relationships → their properties. Used for raw queries.
670
950
  */
671
951
  declare function toNative(value: unknown): unknown;
672
952
 
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 };
953
+ 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 FindSimilarArgs, type FindUniqueArgs, type FulltextIndexNames, 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 SearchArgs, type SearchMode, type SearchResult, type SelectInput, type SelfRelations, type SessionLike, type ShortestPathArgs, type ShortestPathResult, type SimilarResult, type SortOrder, type ToManyRelations, type TransactionLike, type TraversalDirection, type TraversalResult, type TraverseArgs, type TypeMap, type UpdateArgs, type UpdateInput, type UpdateManyArgs, type UpsertArgs, type VectorFilter, type VectorIndexKeys, type VectorKeys, type WhereInput, type WhereUniqueInput, createCuid, createOrm, escapeLucene, toNative, toPlainRecord, toPlainRecords };