@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 +291 -11
- package/dist/index.js +710 -29
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
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
|
-
|
|
281
|
-
|
|
282
|
-
|
|
283
|
-
|
|
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 };
|