index.d.ts 6.8 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160
  1. import { Document } from 'arangojs/documents';
  2. import { DocumentCollection } from 'arangojs/collection';
  3. import { GeneratedAqlQuery } from 'arangojs/aql';
  4. import { Database } from 'arangojs';
  5. /**
  6. * A `CountFn` function returns the number of documents in a single collection matching search `terms` given.
  7. *
  8. * `count()` provides the standard implementation.
  9. */
  10. export declare type CountFn<T extends Searchable, S extends Searchable = T> = (terms?: Terms<Document<DeepNonNullable<S>>>) => Promise<number>;
  11. /**
  12. * Recursively renders all of a complex object's properties required, non-null, and non-undefined.
  13. *
  14. * Note: this type recurses through objects only, not arrays.
  15. */
  16. export declare type DeepNonNullable<T> = NonNullable<T> extends object ? {
  17. [P in keyof T]-?: DeepNonNullable<T[P]>;
  18. } : T;
  19. /** Query sort direction. */
  20. export declare type Direction = 'ASC' | 'DESC';
  21. /**
  22. * Simple search filter type in which any number of conditions can be specified for a presumed parameter.
  23. *
  24. * Multiple operators can be used in combination.
  25. * By default they will be combined into an `AND` filter.
  26. * Specify `mode: "OR"` to switch to an `OR` filter.
  27. *
  28. * Note: `LIKE`, `NOT LIKE`, and regular expression operators are only available if `T` extends `string`.
  29. */
  30. export declare type Filter<T> = {
  31. mode?: 'AND' | 'OR';
  32. eq?: T | null;
  33. gt?: T;
  34. gte?: T;
  35. in?: T[];
  36. like?: T & string;
  37. lt?: T;
  38. lte?: T;
  39. neq?: T | null;
  40. nin?: T[];
  41. nlike?: T & string;
  42. nreg?: T & string;
  43. reg?: T & string;
  44. };
  45. /**
  46. * A `FindFn` function returns the first document in a single collection matching search `terms` given.
  47. * A `sort` can be specified to control the result.
  48. *
  49. * `find()` provides the standard implementation.
  50. */
  51. export declare type FindFn<T extends Searchable, S extends Searchable = T> = (terms?: Terms<Document<DeepNonNullable<S>>>, sort?: Sort<Document<T>>[] | Sort<Document<T>>) => Promise<Document<T> | undefined>;
  52. /**
  53. * Query limit.
  54. * Always a tuple, but the second value can be omitted.
  55. */
  56. export declare type Limit = [number, number?];
  57. /**
  58. * Searchable data type.
  59. * Essentially, any object is valid.
  60. */
  61. export declare type Searchable = Record<string, unknown>;
  62. /**
  63. * Formulate search terms based on a complex data type.
  64. * Nested object types are preserved, while scalar properties are converted to `Filter` representations.
  65. */
  66. export declare type Terms<T> = {
  67. [P in keyof T]?: NonNullable<NonNullable<T[P]> extends object ? Terms<T[P]> : Filter<T[P]>>;
  68. };
  69. /**
  70. * A `SearchFn` function matches documents in a single collection and returns a `SearchResult` based on the given
  71. * `terms`, `limit`, and `sort`.
  72. */
  73. export declare type SearchFn<T extends Searchable, S extends Searchable = T> = (terms?: Terms<Document<DeepNonNullable<S>>>, limit?: Limit, sort?: Sort<Document<S>>[] | Sort<Document<S>>) => Promise<SearchResult<T>>;
  74. /**
  75. * Search results are a tuple of three values:
  76. * 1. The **total** number of matching documents in the searched collection, ignoring limit
  77. * 2. The documents matched within the searched collection, respecting limit
  78. * 3. The AQL query object for the latter (for debugging purposes)
  79. */
  80. export declare type SearchResult<T extends Searchable> = [number, Document<T>[], GeneratedAqlQuery];
  81. /** Query sort order. */
  82. export declare type Sort<T> = [keyof T, Direction];
  83. /** Format scalar or scalar array data for use in AQL. */
  84. export declare const formatData: <T>(data: T | T[]) => string;
  85. /** Format scalar data for use in AQL. */
  86. export declare const formatValue: <T>(data: T) => string;
  87. /** Map of search operator properties to AQL equivalents. */
  88. export declare const operatorMap: Record<keyof Omit<Filter<unknown>, 'mode'>, string>;
  89. /** Search operators. */
  90. export declare const operators: string[];
  91. /**
  92. * Parse a search limit to a string AQL limit.
  93. *
  94. * Note: `LIMIT` is not prepended.
  95. */
  96. export declare const parseLimit: (l: Limit) => string | number;
  97. /**
  98. * Parse a search filter to a string of AQL filters.
  99. *
  100. * Note: `FILTER` is not prepended.
  101. */
  102. export declare const parseFilter: <T>(param: string, search: Filter<T>) => string;
  103. /**
  104. * Parse query sort(s) to an array of string AQL sorts.
  105. *
  106. * Note: `SORT` is not prepended.
  107. */
  108. export declare const parseSort: <T>(s: Sort<T> | Sort<T>[], parent: string) => string[];
  109. /**
  110. * Parse search terms to a flat array of search filters.
  111. * The `parent` argument refers to the current document, and is prefixed to each filter.
  112. */
  113. export declare const parseTerms: <T>(s: Terms<T>, parent: string) => string[];
  114. /**
  115. * Build and execute a count query that matches documents in a single collection.
  116. * Returns the total number of matches.
  117. *
  118. * This example resembles the generated AQL query:
  119. *
  120. * ```aql
  121. * FOR {i} IN {c} {FILTER ...} COLLECT WITH COUNT INTO {n} RETURN {n}
  122. * ```
  123. */
  124. export declare const count: <T extends Searchable, S extends Searchable = T>(db: Database, c: DocumentCollection<T>, i?: string, n?: string) => CountFn<T, S>;
  125. /**
  126. * Build and execute a find query that returns the first matching document in a single collection.
  127. *
  128. * This example resembles the generated AQL query:
  129. *
  130. * ```aql
  131. * FOR {i} IN {collection} {FILTER ...} {SORT ...} LIMIT 1 RETURN {i}
  132. * ```
  133. */
  134. export declare const find: <T extends Searchable, S extends Searchable = T>(db: Database, c: DocumentCollection<T>, i?: string) => FindFn<T, S>;
  135. /**
  136. * Build and execute a search query across a single collection.
  137. * Returns a `SearchResult` tuple containing the total number of matches (ignoring limit), all matching documents
  138. * (respecting limit), and the AQL query.
  139. *
  140. * This example resembles the generated AQL query:
  141. *
  142. * ```aql
  143. * FOR {i} IN {collection} {FILTER ...} {SORT ...} {LIMIT ...} RETURN {i}
  144. * ```
  145. */
  146. export declare const search: <T extends Searchable, S extends Searchable = T>(db: Database, c: DocumentCollection<T>, i?: string, n?: string) => SearchFn<T, S>;
  147. declare const _default: {
  148. count: <T extends Searchable, S extends Searchable = T>(db: Database, c: DocumentCollection<T>, i?: string, n?: string) => CountFn<T, S>;
  149. find: <T_1 extends Searchable, S_1 extends Searchable = T_1>(db: Database, c: DocumentCollection<T_1>, i?: string) => FindFn<T_1, S_1>;
  150. formatData: <T_2>(data: T_2 | T_2[]) => string;
  151. formatValue: <T_3>(data: T_3) => string;
  152. operatorMap: Record<"eq" | "gt" | "gte" | "in" | "like" | "lt" | "lte" | "neq" | "nin" | "nlike" | "nreg" | "reg", string>;
  153. operators: string[];
  154. parseFilter: <T_4>(param: string, search: Filter<T_4>) => string;
  155. parseLimit: (l: Limit) => string | number;
  156. parseSort: <T_5>(s: Sort<T_5> | Sort<T_5>[], parent: string) => string[];
  157. parseTerms: <T_6>(s: Terms<T_6>, parent: string) => string[];
  158. search: <T_7 extends Searchable, S_2 extends Searchable = T_7>(db: Database, c: DocumentCollection<T_7>, i?: string, n?: string) => SearchFn<T_7, S_2>;
  159. };
  160. export default _default;