@iglo.tech/iglo.base 0.0.0-stage → 1.0.1-rc.0

package/dist/types/src/Client.d.ts

@@ -0,0 +1,233 @@
+import type { Loose, LooseObject } from "./tools/loose.js";
+import { BaseAuthStore } from "./stores/BaseAuthStore.js";
+import { SettingsService } from "./services/SettingsService.js";
+import { RecordService } from "./services/RecordService.js";
+import { CollectionService } from "./services/CollectionService.js";
+import { LogService } from "./services/LogService.js";
+import { RealtimeService } from "./services/RealtimeService.js";
+import { HealthService } from "./services/HealthService.js";
+import { FileService } from "./services/FileService.js";
+import { BackupService } from "./services/BackupService.js";
+import { CronService } from "./services/CronService.js";
+import { SQLService } from "./services/SQLService.js";
+import { BatchService } from "./services/BatchService.js";
+import { type RecordModel } from "./tools/dtos.js";
+import { type SendOptions, type FileOptions } from "./tools/options.js";
+export interface BeforeSendResult {
+    [key: string]: Loose;
+    url?: string;
+    options?: LooseObject;
+}
+/**
+ * PocketBase JS Client.
+ */
+export default class Client {
+    /**
+     * The base PocketBase backend url address (eg. 'http://127.0.0.1.8090').
+     */
+    baseURL: string;
+    /**
+     * Legacy getter alias for baseURL.
+     * @deprecated Please replace with baseURL.
+     */
+    get baseUrl(): string;
+    /**
+     * Legacy setter alias for baseURL.
+     * @deprecated Please replace with baseURL.
+     */
+    set baseUrl(v: string);
+    /**
+     * Hook that get triggered right before sending the fetch request,
+     * allowing you to inspect and modify the url and request options.
+     *
+     * For list of the possible options check https://developer.mozilla.org/en-US/docs/Web/API/fetch#options
+     *
+     * You can return a non-empty result object `{ url, options }` to replace the url and request options entirely.
+     *
+     * Example:
+     * ```js
+     * const pb = new PocketBase("https://example.com")
+     *
+     * pb.beforeSend = function (url, options) {
+     *     options.headers = Object.assign({}, options.headers, {
+     *         'X-Custom-Header': 'example',
+     *     })
+     *
+     *     return { url, options }
+     * }
+     *
+     * // use the created client as usual...
+     * ```
+     */
+    beforeSend?: (url: string, options: SendOptions) => BeforeSendResult | Promise<BeforeSendResult>;
+    /**
+     * Hook that get triggered after successfully sending the fetch request,
+     * allowing you to inspect/modify the response object and its parsed data.
+     *
+     * Returns the new Promise resolved `data` that will be returned to the client.
+     *
+     * Example:
+     * ```js
+     * const pb = new PocketBase("https://example.com")
+     *
+     * pb.afterSend = function (response, data, options) {
+     *     if (response.status != 200) {
+     *         throw new ClientResponseError({
+     *             url:      response.url,
+     *             status:   response.status,
+     *             response: { ... },
+     *         })
+     *     }
+     *
+     *     return data;
+     * }
+     *
+     * // use the created client as usual...
+     * ```
+     */
+    afterSend?: ((response: Response, data: Loose) => Loose) & ((response: Response, data: Loose, options: SendOptions) => Loose);
+    /**
+     * Optional language code (default to `en-US`) that will be sent
+     * with the requests to the server as `Accept-Language` header.
+     */
+    lang: string;
+    /**
+     * A replaceable instance of the local auth store service.
+     */
+    authStore: BaseAuthStore;
+    /**
+     * An instance of the service that handles the **Settings APIs**.
+     */
+    readonly settings: SettingsService;
+    /**
+     * An instance of the service that handles the **Collection APIs**.
+     */
+    readonly collections: CollectionService;
+    /**
+     * An instance of the service that handles the **File APIs**.
+     */
+    readonly files: FileService;
+    /**
+     * An instance of the service that handles the **Log APIs**.
+     */
+    readonly logs: LogService;
+    /**
+     * An instance of the service that handles the **Realtime APIs**.
+     */
+    readonly realtime: RealtimeService;
+    /**
+     * An instance of the service that handles the **Health APIs**.
+     */
+    readonly health: HealthService;
+    /**
+     * An instance of the service that handles the **Backup APIs**.
+     */
+    readonly backups: BackupService;
+    /**
+     * An instance of the service that handles the **Cron APIs**.
+     */
+    readonly crons: CronService;
+    /**
+     * An instance of the service that handles the **SQL APIs**.
+     */
+    readonly sql: SQLService;
+    private cancelControllers;
+    private recordServices;
+    private enableAutoCancellation;
+    constructor(baseURL?: string, authStore?: BaseAuthStore | null, lang?: string);
+    /**
+     * @deprecated
+     * With PocketBase v0.23.0 admins are converted to a regular auth
+     * collection named "_superusers", aka. you can use directly collection("_superusers").
+     */
+    get admins(): RecordService;
+    /**
+     * Creates a new batch handler for sending multiple transactional
+     * create/update/upsert/delete collection requests in one network call.
+     *
+     * Example:
+     * ```js
+     * const batch = pb.createBatch();
+     *
+     * batch.collection("example1").create({ ... })
+     * batch.collection("example2").update("RECORD_ID", { ... })
+     * batch.collection("example3").delete("RECORD_ID")
+     * batch.collection("example4").upsert({ ... })
+     *
+     * await batch.send()
+     * ```
+     */
+    createBatch(): BatchService;
+    /**
+     * Returns the RecordService associated to the specified collection.
+     */
+    collection<M = RecordModel>(idOrName: string): RecordService<M>;
+    /**
+     * Globally enable or disable auto cancellation for pending duplicated requests.
+     */
+    autoCancellation(enable: boolean): Client;
+    /**
+     * Cancels single request by its cancellation key.
+     */
+    cancelRequest(requestKey: string): Client;
+    /**
+     * Cancels all pending requests.
+     */
+    cancelAllRequests(): Client;
+    /**
+     * Constructs a filter expression with placeholders populated from a parameters object.
+     *
+     * Placeholder parameters are defined with the `{:paramName}` notation.
+     *
+     * The following parameter values are supported:
+     *
+     * - `string`
+     * - `number`
+     * - `boolean`
+     * - `null`
+     * - `undefined` (stringified as "null")
+     * - `Date` object (_stringified into the PocketBase datetime format_)
+     * - everything else is converted to a string using `JSON.stringify()`
+     *
+     * Example:
+     *
+     * ```js
+     * pb.collection("example").getFirstListItem(pb.filter(
+     *    'title ~ {:title} && created >= {:created}',
+     *    { title: "example", created: new Date()}
+     * ))
+     * ```
+     */
+    filter(raw: string, params?: LooseObject): string;
+    /**
+     * @deprecated Please use `pb.files.getURL()`.
+     */
+    getFileUrl(record: LooseObject, filename: string, queryParams?: FileOptions): string;
+    /**
+     * @deprecated Please use `pb.buildURL()`.
+     */
+    buildUrl(path: string): string;
+    /**
+     * Builds a full client url by safely concatenating the provided path.
+     */
+    buildURL(path: string): string;
+    /**
+     * Sends an api http request.
+     *
+     * @throws {ClientResponseError}
+     */
+    send<T = Loose>(path: string, options: SendOptions): Promise<T>;
+    /**
+     * Shallow copy the provided object and takes care to initialize
+     * any options required to preserve the backward compatability.
+     *
+     * @param  {SendOptions} options
+     * @return {SendOptions}
+     */
+    private initSendOptions;
+    /**
+     * Extracts the header with the provided name in case-insensitive manner.
+     * Returns `null` if no header matching the name is found.
+     */
+    private getHeader;
+}

package/dist/types/src/ClientResponseError.d.ts

@@ -0,0 +1,22 @@
+import type { Loose, LooseObject } from "./tools/loose.js";
+/**
+ * ClientResponseError is a custom Error class that is intended to wrap
+ * and normalize any error thrown by `Client.send()`.
+ */
+export declare class ClientResponseError extends Error {
+    url: string;
+    status: number;
+    response: LooseObject;
+    isAbort: boolean;
+    originalError: Loose;
+    constructor(errData?: unknown);
+    /**
+     * Alias for `this.response` for backward compatibility.
+     */
+    get data(): LooseObject;
+    /**
+     * Make a POJO's copy of the current error class instance.
+     * @see https://github.com/vuex-orm/vuex-orm/issues/255
+     */
+    toJSON(): this;
+}

package/dist/types/src/index.d.ts

@@ -0,0 +1,18 @@
+import Client from "./Client.js";
+export * from "./Client.js";
+export * from "./ClientResponseError.js";
+export * from "./services/CollectionService.js";
+export * from "./services/HealthService.js";
+export * from "./services/LogService.js";
+export * from "./services/RealtimeService.js";
+export * from "./services/RecordService.js";
+export * from "./services/CrudService.js";
+export * from "./services/BatchService.js";
+export * from "./stores/AsyncAuthStore.js";
+export * from "./stores/BaseAuthStore.js";
+export * from "./stores/LocalAuthStore.js";
+export * from "./tools/dtos.js";
+export * from "./tools/options.js";
+export * from "./tools/cookie.js";
+export * from "./tools/jwt.js";
+export default Client;

package/dist/types/src/services/BackupService.d.ts

@@ -0,0 +1,59 @@
+import type { LooseObject } from "../tools/loose.js";
+import { BaseService } from "./BaseService.js";
+import { type CommonOptions } from "../tools/options.js";
+export interface BackupFileInfo {
+    key: string;
+    size: number;
+    modified: string;
+}
+export declare class BackupService extends BaseService {
+    /**
+     * Returns list with all available backup files.
+     *
+     * @throws {ClientResponseError}
+     */
+    getFullList(options?: CommonOptions): Promise<Array<BackupFileInfo>>;
+    /**
+     * Initializes a new backup.
+     *
+     * @throws {ClientResponseError}
+     */
+    create(basename: string, options?: CommonOptions): Promise<boolean>;
+    /**
+     * Uploads an existing backup file.
+     *
+     * Example:
+     *
+     * ```js
+     * await pb.backups.upload({
+     *     file: new Blob([...]),
+     * });
+     * ```
+     *
+     * @throws {ClientResponseError}
+     */
+    upload(bodyParams: LooseObject | FormData, options?: CommonOptions): Promise<boolean>;
+    /**
+     * Deletes a single backup file.
+     *
+     * @throws {ClientResponseError}
+     */
+    delete(key: string, options?: CommonOptions): Promise<boolean>;
+    /**
+     * Initializes an app data restore from an existing backup.
+     *
+     * @throws {ClientResponseError}
+     */
+    restore(key: string, options?: CommonOptions): Promise<boolean>;
+    /**
+     * @deprecated Please use `getDownloadURL()`.
+     */
+    getDownloadUrl(token: string, key: string): string;
+    /**
+     * Builds a download url for a single existing backup using a
+     * superuser file token and the backup file key.
+     *
+     * The file token can be generated via `pb.files.getToken()`.
+     */
+    getDownloadURL(token: string, key: string): string;
+}

package/dist/types/src/services/BaseService.d.ts

@@ -0,0 +1,8 @@
+import Client from "../Client.js";
+/**
+ * BaseService class that should be inherited from all API services.
+ */
+export declare abstract class BaseService {
+    readonly client: Client;
+    constructor(client: Client);
+}

package/dist/types/src/services/BatchService.d.ts

@@ -0,0 +1,56 @@
+import type { Loose, LooseObject } from "../tools/loose.js";
+import { BaseService } from "./BaseService.js";
+import { type SendOptions, type RecordOptions } from "../tools/options.js";
+export interface BatchRequest {
+    method: string;
+    url: string;
+    json?: LooseObject;
+    files?: {
+        [key: string]: Array<Loose>;
+    };
+    headers?: {
+        [key: string]: string;
+    };
+}
+export interface BatchRequestResult {
+    status: number;
+    body: Loose;
+}
+export declare class BatchService extends BaseService {
+    private requests;
+    private subs;
+    /**
+     * Starts constructing a batch request entry for the specified collection.
+     */
+    collection(collectionIdOrName: string): SubBatchService;
+    /**
+     * Sends the batch requests.
+     *
+     * @throws {ClientResponseError}
+     */
+    send(options?: SendOptions): Promise<Array<BatchRequestResult>>;
+}
+export declare class SubBatchService {
+    private requests;
+    private readonly collectionIdOrName;
+    constructor(requests: Array<BatchRequest>, collectionIdOrName: string);
+    /**
+     * Registers a record upsert request into the current batch queue.
+     *
+     * The request will be executed as update if `bodyParams` have a valid existing record `id` value, otherwise - create.
+     */
+    upsert(bodyParams?: LooseObject | FormData, options?: RecordOptions): void;
+    /**
+     * Registers a record create request into the current batch queue.
+     */
+    create(bodyParams?: LooseObject | FormData, options?: RecordOptions): void;
+    /**
+     * Registers a record update request into the current batch queue.
+     */
+    update(id: string, bodyParams?: LooseObject | FormData, options?: RecordOptions): void;
+    /**
+     * Registers a record delete request into the current batch queue.
+     */
+    delete(id: string, options?: SendOptions): void;
+    private prepareRequest;
+}

package/dist/types/src/services/CollectionService.d.ts

@@ -0,0 +1,47 @@
+import type { LooseObject } from "../tools/loose.js";
+import { CrudService } from "./CrudService.js";
+import { type CommonOptions } from "../tools/options.js";
+import { type CollectionModel, type ConfigurableOAuth2Provider } from "../tools/dtos.js";
+export declare class CollectionService extends CrudService<CollectionModel> {
+    /**
+     * @inheritdoc
+     */
+    get baseCrudPath(): string;
+    /**
+     * Imports the provided collections.
+     *
+     * If `deleteMissing` is `true`, all local collections and their fields,
+     * that are not present in the imported configuration, WILL BE DELETED
+     * (including their related records data)!
+     *
+     * @throws {ClientResponseError}
+     */
+    import(collections: Array<CollectionModel>, deleteMissing?: boolean, options?: CommonOptions): Promise<true>;
+    /**
+     * Deletes all records associated with the specified collection.
+     *
+     * @throws {ClientResponseError}
+     */
+    truncate(collectionIdOrName: string, options?: CommonOptions): Promise<true>;
+    /**
+     * Returns type indexed map with scaffolded collection models
+     * populated with their default field values.
+     *
+     * @throws {ClientResponseError}
+     */
+    getScaffolds(options?: CommonOptions): Promise<{
+        [key: string]: CollectionModel;
+    }>;
+    /**
+     * Returns a list with all configurable OAuth2 providers.
+     *
+     * @throws {ClientResponseError}
+     */
+    getAllOAuth2Providers(options?: CommonOptions): Promise<Array<ConfigurableOAuth2Provider>>;
+    /**
+     * Executes the specified view query and returns a sample of the resulting records.
+     *
+     * @throws {ClientResponseError}
+     */
+    dryRunViewQuery(query: string, options?: CommonOptions): Promise<Array<LooseObject>>;
+}

package/dist/types/src/services/CronService.d.ts

@@ -0,0 +1,20 @@
+import { BaseService } from "./BaseService.js";
+import { type CommonOptions } from "../tools/options.js";
+export interface CronJob {
+    id: string;
+    expression: string;
+}
+export declare class CronService extends BaseService {
+    /**
+     * Returns list with all registered cron jobs.
+     *
+     * @throws {ClientResponseError}
+     */
+    getFullList(options?: CommonOptions): Promise<Array<CronJob>>;
+    /**
+     * Runs the specified cron job.
+     *
+     * @throws {ClientResponseError}
+     */
+    run(jobId: string, options?: CommonOptions): Promise<boolean>;
+}

package/dist/types/src/services/CrudService.d.ts

@@ -0,0 +1,85 @@
+import type { LooseObject } from "../tools/loose.js";
+import { BaseService } from "./BaseService.js";
+import { type ListResult } from "../tools/dtos.js";
+import { type CommonOptions, type ListOptions, type FullListOptions } from "../tools/options.js";
+export declare abstract class CrudService<M> extends BaseService {
+    /**
+     * Base path for the crud actions (without trailing slash, eg. '/admins').
+     */
+    abstract get baseCrudPath(): string;
+    /**
+     * Response data decoder.
+     */
+    decode<T = M>(data: Record<string, unknown>): T;
+    /**
+     * Returns a promise with all list items batch fetched at once
+     * (by default 1000 items per request; to change it set the `batch` query param).
+     *
+     * You can use the generic T to supply a wrapper type of the crud model.
+     *
+     * @throws {ClientResponseError}
+     */
+    getFullList<T = M>(options?: FullListOptions): Promise<Array<T>>;
+    /**
+     * Legacy version of getFullList with explicitly specified batch size.
+     */
+    getFullList<T = M>(batch?: number, options?: ListOptions): Promise<Array<T>>;
+    /**
+     * Returns paginated items list.
+     *
+     * You can use the generic T to supply a wrapper type of the crud model.
+     *
+     * @throws {ClientResponseError}
+     */
+    getList<T = M>(page?: number, perPage?: number, options?: ListOptions): Promise<ListResult<T>>;
+    /**
+     * Returns the first found item by the specified filter.
+     *
+     * Internally it calls `getList(1, 1, { filter, skipTotal })` and
+     * returns the first found item.
+     *
+     * You can use the generic T to supply a wrapper type of the crud model.
+     *
+     * For consistency with `getOne`, this method will throw a 404
+     * ClientResponseError if no item was found.
+     *
+     * @throws {ClientResponseError}
+     */
+    getFirstListItem<T = M>(filter: string, options?: CommonOptions): Promise<T>;
+    /**
+     * Returns single item by its id.
+     *
+     * You can use the generic T to supply a wrapper type of the crud model.
+     *
+     * If `id` is empty it will throw a 404 error.
+     *
+     * @throws {ClientResponseError}
+     */
+    getOne<T = M>(id: string, options?: CommonOptions): Promise<T>;
+    /**
+     * Creates a new item.
+     *
+     * You can use the generic T to supply a wrapper type of the crud model.
+     *
+     * @throws {ClientResponseError}
+     */
+    create<T = M>(bodyParams?: LooseObject | FormData, options?: CommonOptions): Promise<T>;
+    /**
+     * Updates an existing item by its id.
+     *
+     * You can use the generic T to supply a wrapper type of the crud model.
+     *
+     * @throws {ClientResponseError}
+     */
+    update<T = M>(id: string, bodyParams?: LooseObject | FormData, options?: CommonOptions): Promise<T>;
+    /**
+     * Deletes an existing item by its id.
+     *
+     * @throws {ClientResponseError}
+     */
+    delete(id: string, options?: CommonOptions): Promise<boolean>;
+    /**
+     * Returns a promise with all list items batch fetched at once.
+     */
+    protected _getFullList<T = M>(batchSize?: number, options?: ListOptions): Promise<Array<T>>;
+}

package/dist/types/src/services/FileService.d.ts

@@ -0,0 +1,19 @@
+import type { LooseObject } from "../tools/loose.js";
+import { BaseService } from "./BaseService.js";
+import { type CommonOptions, type FileOptions } from "../tools/options.js";
+export declare class FileService extends BaseService {
+    /**
+     * @deprecated Please replace with `pb.files.getURL()`.
+     */
+    getUrl(record: LooseObject, filename: string, queryParams?: FileOptions): string;
+    /**
+     * Builds and returns an absolute record file url for the provided filename.
+     */
+    getURL(record: LooseObject, filename: string, queryParams?: FileOptions): string;
+    /**
+     * Requests a new private file access token for the current auth model.
+     *
+     * @throws {ClientResponseError}
+     */
+    getToken(options?: CommonOptions): Promise<string>;
+}

package/dist/types/src/services/HealthService.d.ts

@@ -0,0 +1,16 @@
+import type { LooseObject } from "../tools/loose.js";
+import { BaseService } from "./BaseService.js";
+import { type CommonOptions } from "../tools/options.js";
+export interface HealthCheckResponse {
+    code: number;
+    message: string;
+    data: LooseObject;
+}
+export declare class HealthService extends BaseService {
+    /**
+     * Checks the health status of the api.
+     *
+     * @throws {ClientResponseError}
+     */
+    check(options?: CommonOptions): Promise<HealthCheckResponse>;
+}

package/dist/types/src/services/LogService.d.ts

@@ -0,0 +1,35 @@
+import { BaseService } from "./BaseService.js";
+import { type ListResult, type LogModel } from "../tools/dtos.js";
+import { type CommonOptions, type ListOptions, type LogStatsOptions } from "../tools/options.js";
+export interface HourlyStats {
+    total: number;
+    date: string;
+}
+export declare class LogService extends BaseService {
+    /**
+     * Returns paginated logs list.
+     *
+     * @throws {ClientResponseError}
+     */
+    getList(page?: number, perPage?: number, options?: ListOptions): Promise<ListResult<LogModel>>;
+    /**
+     * Returns a single log by its id.
+     *
+     * If `id` is empty it will throw a 404 error.
+     *
+     * @throws {ClientResponseError}
+     */
+    getOne(id: string, options?: CommonOptions): Promise<LogModel>;
+    /**
+     * Returns logs statistics.
+     *
+     * @throws {ClientResponseError}
+     */
+    getStats(options?: LogStatsOptions): Promise<Array<HourlyStats>>;
+    /**
+     * Deletes all logs.
+     *
+     * @throws {ClientResponseError}
+     */
+    truncate(options?: CommonOptions): Promise<true>;
+}