@xata.io/client 0.0.0-beta.bdce130 → 0.0.0-beta.c21e40a

package/dist/schema/operators.js

@@ -1,39 +1,90 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.includesAll = exports.includesPattern = exports.includesSubstring = exports.includes = exports.contains = exports.isNot = exports.is = exports.pattern = exports.endsWith = exports.startsWith = exports.notExists = exports.exists = exports.le = exports.lte = exports.lt = exports.gte = exports.ge = exports.gt = void 0;
+/**
+ * Operator to restrict results to only values that are greater than the given value.
+ */
 const gt = (value) => ({ $gt: value });
 exports.gt = gt;
+/**
+ * Operator to restrict results to only values that are greater than or equal to the given value.
+ */
 const ge = (value) => ({ $ge: value });
 exports.ge = ge;
+/**
+ * Operator to restrict results to only values that are greater than or equal to the given value.
+ */
 const gte = (value) => ({ $ge: value });
 exports.gte = gte;
+/**
+ * Operator to restrict results to only values that are lower than the given value.
+ */
 const lt = (value) => ({ $lt: value });
 exports.lt = lt;
+/**
+ * Operator to restrict results to only values that are lower than or equal to the given value.
+ */
 const lte = (value) => ({ $le: value });
 exports.lte = lte;
+/**
+ * Operator to restrict results to only values that are lower than or equal to the given value.
+ */
 const le = (value) => ({ $le: value });
 exports.le = le;
+/**
+ * Operator to restrict results to only values that are not null.
+ */
 const exists = (column) => ({ $exists: column });
 exports.exists = exists;
+/**
+ * Operator to restrict results to only values that are null.
+ */
 const notExists = (column) => ({ $notExists: column });
 exports.notExists = notExists;
+/**
+ * Operator to restrict results to only values that start with the given prefix.
+ */
 const startsWith = (value) => ({ $startsWith: value });
 exports.startsWith = startsWith;
+/**
+ * Operator to restrict results to only values that end with the given suffix.
+ */
 const endsWith = (value) => ({ $endsWith: value });
 exports.endsWith = endsWith;
+/**
+ * Operator to restrict results to only values that match the given pattern.
+ */
 const pattern = (value) => ({ $pattern: value });
 exports.pattern = pattern;
+/**
+ * Operator to restrict results to only values that are equal to the given value.
+ */
 const is = (value) => ({ $is: value });
 exports.is = is;
+/**
+ * Operator to restrict results to only values that are not equal to the given value.
+ */
 const isNot = (value) => ({ $isNot: value });
 exports.isNot = isNot;
+/**
+ * Operator to restrict results to only values that contain the given value.
+ */
 const contains = (value) => ({ $contains: value });
 exports.contains = contains;
 // TODO: these can only be applied to columns of type "multiple"
+/**
+ * Operator to restrict results to only arrays that include the given value.
+ */
 const includes = (value) => ({ $includes: value });
 exports.includes = includes;
+/**
+ * Operator to restrict results to only arrays that include a value matching the given substring.
+ */
 const includesSubstring = (value) => ({ $includesSubstring: value });
 exports.includesSubstring = includesSubstring;
+/**
+ * Operator to restrict results to only arrays that include a value matching the given pattern.
+ */
 const includesPattern = (value) => ({ $includesPattern: value });
 exports.includesPattern = includesPattern;
 const includesAll = (value) => ({ $includesAll: value });

package/dist/schema/pagination.d.ts

@@ -1,29 +1,67 @@
-import { XataRecord } from '..';
 import { Query } from './query';
+import { XataRecord } from './record';
 export declare type PaginationQueryMeta = {
     page: {
         cursor: string;
         more: boolean;
     };
 };
-export interface Paginable<T extends XataRecord, R extends XataRecord = T> {
+export interface Paginable<Record extends XataRecord, Result extends XataRecord = Record> {
     meta: PaginationQueryMeta;
-    records: R[];
-    nextPage(size?: number, offset?: number): Promise<Page<T, R>>;
-    previousPage(size?: number, offset?: number): Promise<Page<T, R>>;
-    firstPage(size?: number, offset?: number): Promise<Page<T, R>>;
-    lastPage(size?: number, offset?: number): Promise<Page<T, R>>;
+    records: Result[];
+    nextPage(size?: number, offset?: number): Promise<Page<Record, Result>>;
+    previousPage(size?: number, offset?: number): Promise<Page<Record, Result>>;
+    firstPage(size?: number, offset?: number): Promise<Page<Record, Result>>;
+    lastPage(size?: number, offset?: number): Promise<Page<Record, Result>>;
     hasNextPage(): boolean;
 }
-export declare class Page<T extends XataRecord, R extends XataRecord> implements Paginable<T, R> {
+/**
+ * A Page contains a set of results from a query plus metadata about the retrieved
+ * set of values such as the cursor, required to retrieve additional records.
+ */
+export declare class Page<Record extends XataRecord, Result extends XataRecord = Record> implements Paginable<Record, Result> {
     #private;
+    /**
+     * Page metadata, required to retrieve additional records.
+     */
     readonly meta: PaginationQueryMeta;
-    readonly records: R[];
-    constructor(query: Query<T, R>, meta: PaginationQueryMeta, records?: R[]);
-    nextPage(size?: number, offset?: number): Promise<Page<T, R>>;
-    previousPage(size?: number, offset?: number): Promise<Page<T, R>>;
-    firstPage(size?: number, offset?: number): Promise<Page<T, R>>;
-    lastPage(size?: number, offset?: number): Promise<Page<T, R>>;
+    /**
+     * The set of results for this page.
+     */
+    readonly records: Result[];
+    constructor(query: Query<Record, Result>, meta: PaginationQueryMeta, records?: Result[]);
+    /**
+     * Retrieves the next page of results.
+     * @param size Maximum number of results to be retrieved.
+     * @param offset Number of results to skip when retrieving the results.
+     * @returns The next page or results.
+     */
+    nextPage(size?: number, offset?: number): Promise<Page<Record, Result>>;
+    /**
+     * Retrieves the previous page of results.
+     * @param size Maximum number of results to be retrieved.
+     * @param offset Number of results to skip when retrieving the results.
+     * @returns The previous page or results.
+     */
+    previousPage(size?: number, offset?: number): Promise<Page<Record, Result>>;
+    /**
+     * Retrieves the first page of results.
+     * @param size Maximum number of results to be retrieved.
+     * @param offset Number of results to skip when retrieving the results.
+     * @returns The first page or results.
+     */
+    firstPage(size?: number, offset?: number): Promise<Page<Record, Result>>;
+    /**
+     * Retrieves the last page of results.
+     * @param size Maximum number of results to be retrieved.
+     * @param offset Number of results to skip when retrieving the results.
+     * @returns The last page or results.
+     */
+    lastPage(size?: number, offset?: number): Promise<Page<Record, Result>>;
+    /**
+     * Shortcut method to check if there will be additional results if the next page of results is retrieved.
+     * @returns Whether or not there will be additional results in the next page of results.
+     */
     hasNextPage(): boolean;
 }
 export declare type CursorNavigationOptions = {
@@ -39,3 +77,7 @@ export declare type OffsetNavigationOptions = {
     offset?: number;
 };
 export declare type PaginationOptions = CursorNavigationOptions & OffsetNavigationOptions;
+export declare const PAGINATION_MAX_SIZE = 200;
+export declare const PAGINATION_DEFAULT_SIZE = 200;
+export declare const PAGINATION_MAX_OFFSET = 800;
+export declare const PAGINATION_DEFAULT_OFFSET = 0;

package/dist/schema/pagination.js

@@ -21,7 +21,11 @@ var __classPrivateFieldGet = (this && this.__classPrivateFieldGet) || function (
 };
 var _Page_query;
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.Page = void 0;
+exports.PAGINATION_DEFAULT_OFFSET = exports.PAGINATION_MAX_OFFSET = exports.PAGINATION_DEFAULT_SIZE = exports.PAGINATION_MAX_SIZE = exports.Page = void 0;
+/**
+ * A Page contains a set of results from a query plus metadata about the retrieved
+ * set of values such as the cursor, required to retrieve additional records.
+ */
 class Page {
     constructor(query, meta, records = []) {
         _Page_query.set(this, void 0);
@@ -29,30 +33,61 @@ class Page {
         this.meta = meta;
         this.records = records;
     }
+    /**
+     * Retrieves the next page of results.
+     * @param size Maximum number of results to be retrieved.
+     * @param offset Number of results to skip when retrieving the results.
+     * @returns The next page or results.
+     */
     nextPage(size, offset) {
         return __awaiter(this, void 0, void 0, function* () {
             return __classPrivateFieldGet(this, _Page_query, "f").getPaginated({ page: { size, offset, after: this.meta.page.cursor } });
         });
     }
+    /**
+     * Retrieves the previous page of results.
+     * @param size Maximum number of results to be retrieved.
+     * @param offset Number of results to skip when retrieving the results.
+     * @returns The previous page or results.
+     */
     previousPage(size, offset) {
         return __awaiter(this, void 0, void 0, function* () {
             return __classPrivateFieldGet(this, _Page_query, "f").getPaginated({ page: { size, offset, before: this.meta.page.cursor } });
         });
     }
+    /**
+     * Retrieves the first page of results.
+     * @param size Maximum number of results to be retrieved.
+     * @param offset Number of results to skip when retrieving the results.
+     * @returns The first page or results.
+     */
     firstPage(size, offset) {
         return __awaiter(this, void 0, void 0, function* () {
             return __classPrivateFieldGet(this, _Page_query, "f").getPaginated({ page: { size, offset, first: this.meta.page.cursor } });
         });
     }
+    /**
+     * Retrieves the last page of results.
+     * @param size Maximum number of results to be retrieved.
+     * @param offset Number of results to skip when retrieving the results.
+     * @returns The last page or results.
+     */
     lastPage(size, offset) {
         return __awaiter(this, void 0, void 0, function* () {
             return __classPrivateFieldGet(this, _Page_query, "f").getPaginated({ page: { size, offset, last: this.meta.page.cursor } });
         });
     }
-    // TODO: We need to add something on the backend if we want a hasPreviousPage
+    /**
+     * Shortcut method to check if there will be additional results if the next page of results is retrieved.
+     * @returns Whether or not there will be additional results in the next page of results.
+     */
     hasNextPage() {
         return this.meta.page.more;
     }
 }
 exports.Page = Page;
 _Page_query = new WeakMap();
+exports.PAGINATION_MAX_SIZE = 200;
+exports.PAGINATION_DEFAULT_SIZE = 200;
+exports.PAGINATION_MAX_OFFSET = 800;
+exports.PAGINATION_DEFAULT_OFFSET = 0;

package/dist/schema/query.d.ts

@@ -1,110 +1,118 @@
-import { XataRecord, Repository } from '..';
+import { FilterExpression } from '../api/schemas';
+import { NonEmptyArray, RequiredBy } from '../util/types';
 import { DeepConstraint, FilterConstraints, SortDirection, SortFilter } from './filters';
-import { PaginationOptions, Page, Paginable, PaginationQueryMeta } from './pagination';
-import { Selectable, SelectableColumn, Select } from './selection';
-export declare type QueryOptions<T> = {
+import { Page, Paginable, PaginationOptions, PaginationQueryMeta } from './pagination';
+import { XataRecord } from './record';
+import { Repository } from './repository';
+import { SelectableColumn, SelectedPick, ValueAtColumn } from './selection';
+export declare type QueryOptions<T extends XataRecord> = {
     page?: PaginationOptions;
-    columns?: Array<keyof Selectable<T>>;
+    columns?: NonEmptyArray<SelectableColumn<T>>;
+    filter?: FilterExpression;
     sort?: SortFilter<T> | SortFilter<T>[];
 };
-export declare type FilterExpression = {
-    $exists?: string;
-    $existsNot?: string;
-    $any?: FilterList;
-    $all?: FilterList;
-    $none?: FilterList;
-    $not?: FilterList;
-} & {
-    [key: string]: FilterColumn;
-};
-export declare type FilterList = FilterExpression | FilterExpression[];
-export declare type FilterColumn = FilterColumnIncludes | FilterPredicate | FilterList;
-/**
- * @maxProperties 1
- * @minProperties 1
- */
-export declare type FilterColumnIncludes = {
-    $includes?: FilterPredicate;
-    $includesAny?: FilterPredicate;
-    $includesAll?: FilterPredicate;
-    $includesNone?: FilterPredicate;
-};
-export declare type FilterPredicate = FilterValue | FilterPredicate[] | FilterPredicateOp | FilterPredicateRangeOp;
 /**
- * @maxProperties 1
- * @minProperties 1
+ * Query objects contain the information of all filters, sorting, etc. to be included in the database query.
+ *
+ * Query objects are immutable. Any method that adds more constraints or options to the query will return
+ * a new Query object containing the both the previous and the new constraints and options.
  */
-export declare type FilterPredicateOp = {
-    $any?: FilterPredicate[];
-    $all?: FilterPredicate[];
-    $none?: FilterPredicate | FilterPredicate[];
-    $not?: FilterPredicate | FilterPredicate[];
-    $is?: FilterValue | FilterValue[];
-    $isNot?: FilterValue | FilterValue[];
-    $lt?: FilterRangeValue;
-    $le?: FilterRangeValue;
-    $gt?: FilterRangeValue;
-    $ge?: FilterRangeValue;
-    $contains?: string;
-    $startsWith?: string;
-    $endsWith?: string;
-    $pattern?: string;
-};
-export declare type FilterPredicateRangeOp = {
-    $lt?: FilterRangeValue;
-    $le?: FilterRangeValue;
-    $gt?: FilterRangeValue;
-    $ge?: FilterRangeValue;
-};
-export declare type FilterRangeValue = number | string;
-export declare type FilterValue = number | string | boolean;
-export declare type SortExpression = string[] | {
-    [key: string]: SortOrder;
-} | {
-    [key: string]: SortOrder;
-}[];
-export declare type SortOrder = 'asc' | 'desc';
-export declare type PageConfig = {
-    after?: string;
-    before?: string;
-    first?: string;
-    last?: string;
-    size?: number;
-    offset?: number;
-};
-export declare type ColumnsFilter = string[];
-export declare type QueryTableOptions = {
-    filter: FilterExpression;
-    sort?: SortExpression;
-    page?: PageConfig;
-    columns?: ColumnsFilter;
-};
-export declare class Query<T extends XataRecord, R extends XataRecord = T> implements Paginable<T, R> {
+export declare class Query<Record extends XataRecord, Result extends XataRecord = Record> implements Paginable<Record, Result> {
     #private;
     readonly meta: PaginationQueryMeta;
-    readonly records: R[];
-    constructor(repository: Repository<T> | null, table: string, data: Partial<QueryTableOptions>, parent?: Partial<QueryTableOptions>);
-    getQueryOptions(): QueryTableOptions;
-    any(...queries: Query<T, R>[]): Query<T, R>;
-    all(...queries: Query<T, R>[]): Query<T, R>;
-    not(...queries: Query<T, R>[]): Query<T, R>;
-    none(...queries: Query<T, R>[]): Query<T, R>;
-    filter(constraints: FilterConstraints<T>): Query<T, R>;
-    filter<F extends keyof T>(column: F, value: FilterConstraints<T[F]> | DeepConstraint<T[F]>): Query<T, R>;
-    sort<F extends keyof T>(column: F, direction: SortDirection): Query<T, R>;
-    select<K extends SelectableColumn<T>>(columns: K[]): Query<T, Select<T, K>>;
-    getPaginated<Options extends QueryOptions<T>>(options?: Options): Promise<Page<T, typeof options['columns'] extends SelectableColumn<T>[] ? Select<T, typeof options['columns'][number]> : R>>;
-    [Symbol.asyncIterator](): AsyncIterableIterator<R>;
-    getIterator(chunk: number, options?: Omit<QueryOptions<T>, 'page'>): AsyncGenerator<R[]>;
-    getMany<Options extends QueryOptions<T>>(options?: Options): Promise<(typeof options['columns'] extends SelectableColumn<T>[] ? Select<T, typeof options['columns'][number]> : R)[]>;
-    getOne<Options extends Omit<QueryOptions<T>, 'page'>>(options?: Options): Promise<(typeof options['columns'] extends SelectableColumn<T>[] ? Select<T, typeof options['columns'][number]> : R) | null>;
-    /**async deleteAll(): Promise<number> {
-      // TODO: Return number of affected rows
-      return 0;
-    }**/
-    nextPage(size?: number, offset?: number): Promise<Page<T, R>>;
-    previousPage(size?: number, offset?: number): Promise<Page<T, R>>;
-    firstPage(size?: number, offset?: number): Promise<Page<T, R>>;
-    lastPage(size?: number, offset?: number): Promise<Page<T, R>>;
+    readonly records: Result[];
+    constructor(repository: Repository<Record> | null, table: string, data: Partial<QueryOptions<Record>>, parent?: Partial<QueryOptions<Record>>);
+    getQueryOptions(): QueryOptions<Record>;
+    /**
+     * Builds a new query object representing a logical OR between the given subqueries.
+     * @param queries An array of subqueries.
+     * @returns A new Query object.
+     */
+    any(...queries: Query<Record, Result>[]): Query<Record, Result>;
+    /**
+     * Builds a new query object representing a logical AND between the given subqueries.
+     * @param queries An array of subqueries.
+     * @returns A new Query object.
+     */
+    all(...queries: Query<Record, Result>[]): Query<Record, Result>;
+    /**
+     * Builds a new query object representing a logical OR negating each subquery. In pseudo-code: !q1 OR !q2
+     * @param queries An array of subqueries.
+     * @returns A new Query object.
+     */
+    not(...queries: Query<Record, Result>[]): Query<Record, Result>;
+    /**
+     * Builds a new query object representing a logical AND negating each subquery. In pseudo-code: !q1 AND !q2
+     * @param queries An array of subqueries.
+     * @returns A new Query object.
+     */
+    none(...queries: Query<Record, Result>[]): Query<Record, Result>;
+    /**
+     * Builds a new query object adding one or more constraints. Examples:
+     *
+     * ```
+     * query.filter("columnName", columnValue)
+     * query.filter({
+     *   "columnName": columnValue
+     * })
+     * query.filter({
+     *   "columnName": operator(columnValue) // Use gt, gte, lt, lte, startsWith,...
+     * })
+     * ```
+     *
+     * @param constraints
+     * @returns A new Query object.
+     */
+    filter(constraints: FilterConstraints<Record>): Query<Record, Result>;
+    filter<F extends SelectableColumn<Record>>(column: F, value: FilterConstraints<ValueAtColumn<Record, F>> | DeepConstraint<ValueAtColumn<Record, F>>): Query<Record, Result>;
+    /**
+     * Builds a new query with a new sort option.
+     * @param column The column name.
+     * @param direction The direction. Either ascending or descending.
+     * @returns A new Query object.
+     */
+    sort<F extends SelectableColumn<Record>>(column: F, direction: SortDirection): Query<Record, Result>;
+    /**
+     * Builds a new query specifying the set of columns to be returned in the query response.
+     * @param columns Array of column names to be returned by the query.
+     * @returns A new Query object.
+     */
+    select<K extends SelectableColumn<Record>>(columns: NonEmptyArray<K>): Query<Record, SelectedPick<Record, NonEmptyArray<K>>>;
+    getPaginated(): Promise<Page<Record, Result>>;
+    getPaginated(options: Omit<QueryOptions<Record>, 'columns'>): Promise<Page<Record, Result>>;
+    getPaginated<Options extends RequiredBy<QueryOptions<Record>, 'columns'>>(options: Options): Promise<Page<Record, SelectedPick<Record, typeof options['columns']>>>;
+    [Symbol.asyncIterator](): AsyncIterableIterator<Result>;
+    getIterator(chunk: number): AsyncGenerator<Result[]>;
+    getIterator(chunk: number, options: Omit<QueryOptions<Record>, 'columns' | 'page'>): AsyncGenerator<Result[]>;
+    getIterator<Options extends RequiredBy<Omit<QueryOptions<Record>, 'page'>, 'columns'>>(chunk: number, options: Options): AsyncGenerator<SelectedPick<Record, typeof options['columns']>[]>;
+    /**
+     * Performs the query in the database and returns a set of results.
+     * @param options Additional options to be used when performing the query.
+     * @returns An array of records from the database.
+     */
+    getMany(): Promise<Result[]>;
+    getMany(options: Omit<QueryOptions<Record>, 'columns'>): Promise<Result[]>;
+    getMany<Options extends RequiredBy<QueryOptions<Record>, 'columns'>>(options: Options): Promise<SelectedPick<Record, typeof options['columns']>[]>;
+    /**
+     * Performs the query in the database and returns all the results.
+     * Warning: If there are a large number of results, this method can have performance implications.
+     * @param options Additional options to be used when performing the query.
+     * @returns An array of records from the database.
+     */
+    getAll(chunk?: number): Promise<Result[]>;
+    getAll(chunk: number | undefined, options: Omit<QueryOptions<Record>, 'columns' | 'page'>): Promise<Result[]>;
+    getAll<Options extends RequiredBy<Omit<QueryOptions<Record>, 'page'>, 'columns'>>(chunk: number | undefined, options: Options): Promise<SelectedPick<Record, typeof options['columns']>[]>;
+    /**
+     * Performs the query in the database and returns the first result.
+     * @param options Additional options to be used when performing the query.
+     * @returns The first record that matches the query, or null if no record matched the query.
+     */
+    getOne(): Promise<Result | null>;
+    getOne(options: Omit<QueryOptions<Record>, 'columns' | 'page'>): Promise<Result | null>;
+    getOne<Options extends RequiredBy<Omit<QueryOptions<Record>, 'page'>, 'columns'>>(options: Options): Promise<SelectedPick<Record, typeof options['columns']> | null>;
+    nextPage(size?: number, offset?: number): Promise<Page<Record, Result>>;
+    previousPage(size?: number, offset?: number): Promise<Page<Record, Result>>;
+    firstPage(size?: number, offset?: number): Promise<Page<Record, Result>>;
+    lastPage(size?: number, offset?: number): Promise<Page<Record, Result>>;
     hasNextPage(): boolean;
 }