lazypock 0.1.3 → 0.1.6

package/dist/index.d.cts

@@ -50,11 +50,39 @@ interface RequestOptions {
     signal?: AbortSignal;
     /** Custom fetch implementation (for RN or test mocking) */
     fetch?: typeof globalThis.fetch;
+    /**
+     * Request identifier used by the auto-cancellation mechanism.
+     *
+     * Pending requests sharing the same key cancel each other — only the
+     * last one is executed (PocketBase `requestKey` semantics).
+     *
+     * - `string` — use this exact key instead of the default `METHOD + path`.
+     * - `null` — disable auto-cancellation for this request (never auto-cancelled).
+     *
+     * @default `${method} ${path}`
+     */
+    requestKey?: string | null;
+    /**
+     * Disable auto-cancellation for this request.
+     * Alias of `requestKey: null` (PocketBase `$autoCancel: false` compat).
+     */
+    autoCancel?: boolean;
+    /**
+     * Custom request key used for auto-cancellation.
+     * Alias of `requestKey` (PocketBase `$cancelKey` compat).
+     */
+    cancelKey?: string;
 }
 declare class ApiError extends Error {
     readonly data: unknown;
     readonly status: number;
-    constructor(message: string, data: unknown, status: number);
+    /**
+     * `true` when this error was caused by an aborted/cancelled request
+     * (auto-cancelled duplicate, or manually via `cancelRequest()` /
+     * `cancelAllRequests()` / an external AbortSignal).
+     */
+    readonly isAbort: boolean;
+    constructor(message: string, data: unknown, status: number, isAbort?: boolean);
 }
 
 /**
@@ -130,29 +158,51 @@ declare class AuthStore {
     private notify;
 }
 
-/**
- * Low-level HTTP client wrapping `fetch` with automatic auth token injection.
- * Only relies on `globalThis.fetch` — works in browser, React Native, and Node 18+.
- */
 declare class HttpClient {
     private baseUrl;
     private authStore;
     private defaultFetch;
+    /**
+     * Abort controllers for in-flight requests, keyed by their cancellation key
+     * (default `METHOD path`). A new request with the same key aborts the
+     * previous one — PocketBase-style auto-cancellation of duplicated requests.
+     */
+    private cancelControllers;
+    /** Global toggle for the auto-cancellation behaviour (default: on). */
+    private enableAutoCancellation;
     /**
      * @param baseUrl The API base URL (e.g. `http://localhost:4000/api`). Trailing slash stripped.
      * @param authStore The auth store providing the token for Authorization headers.
      */
     constructor(baseUrl: string, authStore: AuthStore);
     private refreshAuth;
+    /**
+     * Globally enable or disable auto-cancellation of duplicated pending requests.
+     * Fluent — returns `this` for chaining.
+     */
+    autoCancellation(enable: boolean): this;
+    /**
+     * Abort a pending request identified by its cancellation key
+     * (default `METHOD path`, e.g. `"GET /api/posts"`). No-op if not pending.
+     */
+    cancelRequest(requestKey: string): this;
+    /** Abort all pending requests. */
+    cancelAllRequests(): this;
     /**
      * Make an HTTP request with automatic auth token injection and optional auto-refresh.
      *
+     * Auto-cancellation: a request keyed by `options.requestKey` (default
+     * `METHOD path`) aborts any previous pending request with the same key,
+     * so only the last duplicate executes. Set `requestKey: null` or
+     * `autoCancel: false` to opt out per request.
+     *
      * @param method HTTP method.
      * @param path URL path (appended to baseUrl).
      * @param body JSON-serializable body, or FormData for file uploads.
      * @param options Optional request options.
      * @returns Parsed JSON response, or null for 204 No Content.
-     * @throws {ApiError} On non-2xx responses.
+     * @throws {ApiError} On non-2xx responses or when the request is aborted
+     * (aborted requests throw an `ApiError` with `isAbort === true`).
      */
     request<T = unknown>(method: Method, path: string, body?: unknown, options?: RequestOptions): Promise<T | null>;
     /**
@@ -288,11 +338,27 @@ declare class CollectionService<T = ApiRecord> {
     constructor(http: HttpClient, collectionName: string, authStore?: AuthStore, realtime?: RealtimeService);
     private encodeId;
     /**
-     * List records with optional filter/sort/pagination.
-     * @param params Query parameters including `filter`, `sort`, `page`, `perPage`, `expand`.
+     * Fetch a paginated list of records (PocketBase `getList`).
+     *
+     * @param page Page number (default 1).
+     * @param perPage Records per page (default 30).
+     * @param options Query params (`filter`, `sort`, `expand`, `fields`) + request options.
+     */
+    getList<T2 = T>(page?: number, perPage?: number, options?: Record<string, unknown> & RequestOptions): Promise<ListResult<T2> | null>;
+    /**
+     * Fetch all records at once (auto-paginates). Mirrors PocketBase's
+     * `pb.collection(name).getFullList()`.
+     *
+     * @param options Query params (`sort`, `filter`, `batch`, etc.) + request options.
+     */
+    getFullList<T2 = T>(options?: Record<string, unknown> & RequestOptions): Promise<Array<T2>>;
+    /**
+     * Fetch the first record matching a filter (PocketBase `getFirstListItem`).
+     *
+     * @param filter Filter expression (e.g. `title = 'x'`).
      * @param options Optional request options.
      */
-    list(params?: Record<string, string>, options?: RequestOptions): Promise<ListResult<T> | null>;
+    getFirstListItem<T2 = T>(filter: string, options?: RequestOptions): Promise<T2 | null>;
     /**
      * Get a single record by ID.
      * @param id Record ID.
@@ -393,12 +459,28 @@ interface FileRecord {
     mimeType: string;
     size: number;
     url: string;
+    /** Map of thumbnail size => URL, e.g. { "50x50": "/api/files/<id>/thumbs/50x50" } */
+    thumbs?: Record<string, string>;
     [key: string]: unknown;
 }
 /**
  * Construct a file URL from the API base URL and file ID.
  */
 declare function getFileUrl(baseUrl: string, fileId: string): string;
+/**
+ * Construct a thumbnail URL from the API base URL, file ID, and thumb size.
+ * @param size e.g. "50x50"
+ */
+declare function getThumbUrl(baseUrl: string, fileId: string, size: string): string;
+/**
+ * Construct an on-demand scaled image URL from the API base URL, file ID, and size.
+ *
+ * The size is an ImageMagick geometry: "100" (width, keep aspect), "100x100"
+ * (fit within box), "100x100!" (exact crop), "x200" (height). The server
+ * generates and caches the scaled image on first request.
+ * @param size e.g. "100x100"
+ */
+declare function getScaleUrl(baseUrl: string, fileId: string, size: string): string;
 /**
  * Service for file upload, retrieval, and deletion.
  * Access via {@link LazypockClient.files}.
@@ -419,6 +501,27 @@ declare class FilesService {
         recordId?: string;
         fieldName?: string;
     }): Promise<FileRecord | null>;
+    /**
+     * List uploaded files (newest first), with optional filters.
+     *
+     * @param options Filters and pagination.
+     */
+    list(options?: {
+        page?: number;
+        perPage?: number;
+        collectionName?: string;
+        fieldName?: string;
+        mime?: string;
+    }): Promise<{
+        items: FileRecord[];
+        page: number;
+        perPage: number;
+        total: number;
+    }>;
+    /**
+     * Fetch file metadata including URL.
+     * @param fileId The file ID.
+     */
     /**
      * Fetch file metadata including URL.
      * @param fileId The file ID.
@@ -432,6 +535,82 @@ declare class FilesService {
     delete(fileId: string, options?: RequestOptions): Promise<null>;
 }
 
+/**
+ * Registry-level realtime events for the collections admin channel.
+ * The backend (AdminChannel) broadcasts the action as the *event name*,
+ * with the collection JSON as the payload.
+ */
+interface CollectionsMessage {
+    action: "create" | "update" | "delete";
+    /** The collection payload (id + metadata), or {} when unavailable. */
+    collection: Record<string, unknown>;
+    topic?: string;
+}
+/**
+ * Registry service for collections (list/create/update/delete + realtime
+ * registry events). Mirrors PocketBase's `pb.collections`.
+ */
+declare class CollectionsService {
+    private http?;
+    private realtime?;
+    /** @internal */
+    constructor(http?: HttpClient, realtime?: RealtimeService);
+    /**
+     * Fetch a paginated list of collections (admin).
+     *
+     * @param params Optional query params (`page`, `perPage`, `filter`, `sort`).
+     * @param options Optional request options.
+     */
+    getList<T = ApiRecord>(params?: Record<string, unknown>, options?: RequestOptions): Promise<ListResult<T> | null>;
+    /**
+     * Fetch all collections at once (auto-paginates). Mirrors PocketBase's
+     * `pb.collections.getFullList()` — defaults to listing everything.
+     *
+     * @param options Query params (`sort`, `batch`, etc.) or request options.
+     */
+    getFullList<T = ApiRecord>(options?: Record<string, unknown> & RequestOptions): Promise<Array<T>>;
+    /**
+     * Get a single collection by ID or name (admin).
+     *
+     * @param id Collection ID or name.
+     * @param options Optional request options.
+     */
+    getOne<T = ApiRecord>(id: string, options?: RequestOptions): Promise<T | null>;
+    /**
+     * Create a new collection (admin).
+     *
+     * @param data Collection definition (name, type, fields, options, rules, etc.).
+     * @param options Optional request options.
+     */
+    create<T = ApiRecord>(data: Record<string, unknown>, options?: RequestOptions): Promise<T | null>;
+    /**
+     * Update an existing collection (admin).
+     *
+     * @param id Collection ID or name.
+     * @param data Updated collection fields.
+     * @param options Optional request options.
+     */
+    update<T = ApiRecord>(id: string, data: Record<string, unknown>, options?: RequestOptions): Promise<T | null>;
+    /**
+     * Delete a collection (admin).
+     *
+     * @param id Collection ID or name.
+     * @param options Optional request options.
+     */
+    delete(id: string, options?: RequestOptions): Promise<boolean>;
+    /**
+     * Subscribe to collection registry changes.
+     *
+     * @param callback Received on every collection create/update/delete.
+     * @returns A function that unsubscribes this callback.
+     */
+    subscribe(callback: (e: CollectionsMessage) => void): () => void;
+    /**
+     * Unsubscribe all callbacks from the registry channel.
+     */
+    unsubscribe(): void;
+}
+
 /** A single field definition as returned by `GET /collections`. */
 interface SchemaField {
     id?: string;
@@ -534,13 +713,14 @@ interface LazypockClientOptions {
  * ```ts
  * const client = new LazypockClient({ baseUrl: 'http://localhost:4000/api' });
  * await client.login('admin@example.com', 'password');
- * const posts = await client.collection('posts').list();
+ * const posts = await client.collection('posts').getList();
  * ```
  */
 declare class LazypockClient {
     readonly http: HttpClient;
     readonly authStore: AuthStore;
     readonly realtime: RealtimeService;
+    readonly collections: CollectionsService;
     readonly files: FilesService;
     private collectionCache;
     private schemaByName?;
@@ -577,6 +757,27 @@ declare class LazypockClient {
     generateTypes(options?: {
         packageName?: string;
     }): string;
+    /**
+     * Globally enable or disable auto-cancellation of duplicated pending requests.
+     *
+     * When enabled (default), a new request whose `requestKey` (default
+     * `HTTP_METHOD + path`) matches a still-pending request aborts the previous
+     * one — only the last duplicate executes.
+     *
+     * @example
+     * ```ts
+     * client.autoCancellation(false); // keep every request
+     * ```
+     */
+    autoCancellation(enable: boolean): this;
+    /**
+     * Abort a single pending request by its cancellation key
+     * (default `HTTP_METHOD + path`, e.g. `"GET /api/posts?page=1"`).
+     * The request rejects with an `ApiError` whose `isAbort` is `true`.
+     */
+    cancelRequest(requestKey: string): this;
+    /** Abort all pending requests. */
+    cancelAllRequests(): this;
     /** Check whether any superuser exists (for login vs setup screen routing). */
     checkSuperuser(): Promise<{
         has_superuser: boolean;
@@ -635,79 +836,6 @@ declare class LazypockClient {
     logout(): void;
     /** Ping the API health endpoint. */
     health(options?: RequestOptions): Promise<Record<string, unknown> | null>;
-    /**
-     * List all collections (admin).
-     * @param q URL query string (e.g. `page=1&perPage=200`).
-     * @param options Optional request options.
-     */
-    listCollections(q?: string, options?: RequestOptions): Promise<ListResult<ApiRecord> | null>;
-    /**
-     * Get a single collection by ID or name.
-     * @param id Collection ID or name.
-     * @param options Optional request options.
-     */
-    getCollection(id: string, options?: RequestOptions): Promise<ApiRecord | null>;
-    /**
-     * Create a new collection (admin).
-     * @param data Collection definition (name, type, fields, options, rules, etc.).
-     * @param options Optional request options.
-     */
-    createCollection(data: Record<string, unknown>, options?: RequestOptions): Promise<ApiRecord | null>;
-    /**
-     * Update an existing collection (admin).
-     * @param id Collection ID or name.
-     * @param data Updated collection fields.
-     * @param options Optional request options.
-     */
-    updateCollection(id: string, data: Record<string, unknown>, options?: RequestOptions): Promise<ApiRecord | null>;
-    /**
-     * Delete a collection (admin).
-     * @param id Collection ID or name.
-     * @param options Optional request options.
-     */
-    deleteCollection(id: string, options?: RequestOptions): Promise<null>;
-    /**
-     * List records from a dynamic collection with optional filter/sort/pagination.
-     *
-     * @param coll Collection name.
-     * @param params Query parameters including:
-     *   - `filter` — PocketBase filter syntax (e.g. `title~'hello' && published=true`)
-     *   - `sort` — Comma-separated, `-` prefix for DESC (e.g. `-created,title`)
-     *   - `page` — Page number (default: 1)
-     *   - `perPage` — Items per page (default: 30, max: 200)
-     *   - `expand` — Comma-separated relation fields (e.g. `author,category`)
-     * @param options Optional request options.
-     */
-    listRecords(coll: string, params?: Record<string, string>, options?: RequestOptions): Promise<ListResult<ApiRecord> | null>;
-    /**
-     * Get a single record by ID.
-     * @param coll Collection name.
-     * @param id Record ID.
-     * @param options Optional request options.
-     */
-    getRecord(coll: string, id: string, options?: RequestOptions): Promise<ApiRecord | null>;
-    /**
-     * Create a record in a dynamic collection.
-     * @param coll Collection name.
-     * @param data Record fields.
-     * @param options Optional request options.
-     */
-    createRecord(coll: string, data: Record<string, unknown>, options?: RequestOptions): Promise<ApiRecord | null>;
-    /**
-     * Update a record in a dynamic collection.
-     * @param coll Collection name.
-     * @param id Record ID.
-     * @param data Updated record fields.
-     * @param options Optional request options.
-     */
-    updateRecord(coll: string, id: string, data: Record<string, unknown>, options?: RequestOptions): Promise<ApiRecord | null>;
-    /**
-     * Delete a record from a dynamic collection.
-     * @param coll Collection name.
-     * @param id Record ID.
-     * @param options Optional request options.
-     */
-    deleteRecord(coll: string, id: string, options?: RequestOptions): Promise<null>;
 }
 
 /**
@@ -738,4 +866,4 @@ declare class TypedClient<TCollections extends LazypockCollections = LazypockCol
  */
 declare function createClient<TCollections extends LazypockCollections = LazypockCollections>(options: LazypockClientOptions): TypedClient<TCollections>;
 
-export { ApiError, type ApiRecord, type AuthModel, AuthStore, type CollectionSchema, CollectionService, type CreateData, type FileRecord, FilesService, LazypockClient, type LazypockClientOptions, type LazypockCollections, type ListResult, type RealtimeCallback, type RealtimeMessage, RealtimeService, type RecordShape, type RequestOptions, type SchemaField, type StorageAdapter, type SystemFields, TypedClient, type UpdateData, collectionTypeName, createClient, fieldTypeKind, fieldTypeScriptType, generateTypes, getFileUrl, schemaFieldType, wsUrlFromBaseUrl };
+export { ApiError, type ApiRecord, type AuthModel, AuthStore, type CollectionSchema, CollectionService, type CollectionsMessage, CollectionsService, type CreateData, type FileRecord, FilesService, HttpClient, LazypockClient, type LazypockClientOptions, type LazypockCollections, type ListResult, type RealtimeCallback, type RealtimeMessage, RealtimeService, type RecordShape, type RequestOptions, type SchemaField, type StorageAdapter, type SystemFields, TypedClient, type UpdateData, collectionTypeName, createClient, fieldTypeKind, fieldTypeScriptType, generateTypes, getFileUrl, getScaleUrl, getThumbUrl, schemaFieldType, wsUrlFromBaseUrl };