lazypock 0.1.5 → 0.2.0

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>;
     /**
@@ -409,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}.
@@ -435,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.
@@ -670,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;
@@ -698,7 +806,11 @@ declare class LazypockClient {
     login(email: string, password: string, collection?: string): Promise<({
         token: string;
     } & Record<string, unknown>) | null>;
-    /** Fetch the current superuser profile and refresh the auth model. */
+    /**
+     * Fetch the current authenticated identity (superuser OR auth collection user).
+     * Uses `GET /api/me` (PocketBase parity) — works with both superuser tokens
+     * and auth collection user tokens.
+     */
     me<T = ApiRecord>(options?: RequestOptions): Promise<T | null>;
     /**
      * Authenticate against an auth collection with email/password.
@@ -758,4 +870,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 CollectionsMessage, CollectionsService, 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 };

package/dist/index.d.ts

@@ -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>;
     /**
@@ -409,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}.
@@ -435,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.
@@ -670,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;
@@ -698,7 +806,11 @@ declare class LazypockClient {
     login(email: string, password: string, collection?: string): Promise<({
         token: string;
     } & Record<string, unknown>) | null>;
-    /** Fetch the current superuser profile and refresh the auth model. */
+    /**
+     * Fetch the current authenticated identity (superuser OR auth collection user).
+     * Uses `GET /api/me` (PocketBase parity) — works with both superuser tokens
+     * and auth collection user tokens.
+     */
     me<T = ApiRecord>(options?: RequestOptions): Promise<T | null>;
     /**
      * Authenticate against an auth collection with email/password.
@@ -758,4 +870,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 CollectionsMessage, CollectionsService, 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 };