lazypock 0.4.0 → 0.6.0

package/dist/index.d.ts

@@ -50,21 +50,6 @@ interface RequestOptions {
     signal?: AbortSignal;
     /** Custom fetch implementation (for RN or test mocking) */
     fetch?: typeof globalThis.fetch;
-    /**
-     * Cache control for this request (see {@link CacheRequestOptions}).
-     * Resolved against the client's global cache config when unset.
-     */
-    cache?: boolean | number | {
-        ttl?: number;
-        key?: string;
-    };
-    /** Alias of `cache: <ms>` — cache this GET for `ttl` milliseconds. */
-    ttl?: number;
-    /**
-     * Extra cache namespaces to invalidate when this mutation succeeds.
-     * The current collection is always invalidated automatically.
-     */
-    invalidate?: string[];
     /**
      * Request identifier used by the auto-cancellation mechanism.
      *
@@ -110,6 +95,79 @@ declare class ApiError extends Error {
     readonly isAbort: boolean;
     constructor(message: string, data: unknown, status: number, isAbort?: boolean);
 }
+/**
+ * String keys of a record shape (excludes methods/symbols).
+ * Falls back to `string` when `T` has no known keys (e.g. `unknown`), so
+ * untyped services accept any field name.
+ */
+type FieldKey<T> = Extract<keyof T, string> extends never ? string : Extract<keyof T, string>;
+/** Valid filter operators, matching the backend FilterCompiler. */
+type FilterOp = "=" | "!=" | "~" | "!~" | ">" | ">=" | "<" | "<=";
+/** One `field op value` clause. */
+type FilterClause<T> = `${FieldKey<T>} ${FilterOp} ${string}`;
+/**
+ * Type-checked filter expression (PocketBase syntax).
+ *
+ * ```ts
+ * getList(1, 20, { filter: "title ~ 'x' && published = true" })
+ * getList(1, 20, { filter: "(title = 'a' || title = 'b')" })
+ * ```
+ *
+ * The first clause's field name + operator are validated; the rest of the
+ * expression (values, `&&`/`||`, parens, `!`) is free-form.
+ */
+type FilterString<T> = FilterClause<T> | `${FilterClause<T>}${string}`;
+/** A single `[+|-]field` sort token. */
+type SortField<T> = `${"" | "-" | "+"}${FieldKey<T>}`;
+/**
+ * Type-checked sort string: `field`, `-field` (desc), `+field`, or
+ * comma-separated combinations (e.g. `"-created,title"`).
+ */
+type SortString<T> = SortField<T> | `${SortField<T>},${string}`;
+/**
+ * Type-checked expand string: comma-separated relation field names
+ * (e.g. `"author"` or `"author,category"`). Non-relation fields are
+ * warned about at runtime when a schema is available.
+ */
+type ExpandString<T> = FieldKey<T> | `${FieldKey<T>},${string}`;
+/**
+ * Query options for list/read operations, typed against a record shape `T`.
+ *
+ * `filter`, `sort`, `expand` and `fields` are recognized; any other key is
+ * passed through as a raw query parameter (PocketBase-compatible).
+ */
+interface ListOptions<T = ApiRecord> {
+    /**
+     * PocketBase filter expression. Field names + operators are type-checked
+     * when `T` is a concrete shape.
+     */
+    filter?: FilterString<T>;
+    /**
+     * Sort field(s): `field`, `-field` (descending), comma-separated.
+     */
+    sort?: SortString<T>;
+    /**
+     * Comma-separated relation field names to expand.
+     */
+    expand?: ExpandString<T>;
+    /**
+     * Explicit field projection (overrides {@link CollectionService.select}).
+     */
+    fields?: string;
+    /**
+     * Raw query parameters — any other key is passed through verbatim.
+     */
+    [key: string]: unknown;
+}
+/**
+ * Options for single-record reads (`getOne`): expand + explicit fields.
+ */
+interface ReadOptions<T = ApiRecord> {
+    /** Comma-separated relation field names to expand. */
+    expand?: ExpandString<T>;
+    /** Explicit field projection (overrides {@link CollectionService.select}). */
+    fields?: string;
+}
 
 /**
  * Interface for pluggable persistence backends.
@@ -184,147 +242,10 @@ declare class AuthStore {
     private notify;
 }
 
-/** Options for enabling/customising the client's query cache. */
-interface CacheConfig {
-    /**
-     * Master switch. When `true`, readable GET requests are cached with the
-     * default TTL unless a request opts out via `{ cache: false }`.
-     *
-     * When `false` (default), caching is disabled unless a request opts in
-     * via `{ cache: true }` or `{ ttl: <ms> }`. Opt-in works regardless.
-     */
-    enabled?: boolean;
-    /**
-     * Default time-to-live for cached entries, in milliseconds.
-     * @default 60_000 (1 minute)
-     */
-    defaultTTL?: number;
-    /**
-     * Optional persistence backend (same interface as AuthStore's storage).
-     * Defaults to an in-memory Map — swap for `localStorage` / `AsyncStorage`
-     * to keep the cache across page reloads / app restarts.
-     */
-    store?: StorageAdapter;
-    /**
-     * Max number of entries to keep in memory (LRU eviction).
-     * @default 500
-     */
-    maxEntries?: number;
-    /**
-     * When true and the client has an active realtime subscription for a
-     * collection, inbound create/update/delete events invalidate that
-     * collection's cached entries automatically.
-     * @default false — only local mutations invalidate (explicit + predictable)
-     */
-    invalidateOnRealtime?: boolean;
-}
-/** Per-request cache controls (mixed into {@link RequestOptions}). */
-interface CacheRequestOptions {
-    /**
-     * Cache control for this request:
-     * - `true` — cache with the default (or global) TTL
-     * - `false` — always fetch fresh, bypass cache (and don't store the result)
-     * - a number — cache with this TTL in milliseconds
-     * - an object — `{ ttl, key }` for finer control
-     *
-     * When unset, the global `cache.enabled` flag decides.
-     */
-    cache?: boolean | number | {
-        ttl?: number;
-        key?: string;
-    };
-    /** Alias of `cache: <ms>` (convenience, reads naturally). */
-    ttl?: number;
-    /**
-     * Extra cache namespaces to invalidate when this mutation succeeds.
-     * The current collection is always invalidated automatically.
-     * @example create({ ... }, { invalidate: ['users'] })
-     */
-    invalidate?: string[];
-}
-/** LRU-ish memory store + optional persistent adapter hybrid. */
-declare class CacheStore {
-    private memory;
-    private readonly ttl;
-    private readonly persistence?;
-    private readonly maxEntries;
-    private hits;
-    private misses;
-    private namespaceEntries;
-    /** Key → set of prefix tags registered for that key (e.g. `getList:posts`). */
-    private prefixEntries;
-    constructor(config?: {
-        defaultTTL?: number;
-        store?: StorageAdapter;
-        maxEntries?: number;
-    });
-    /** Resolve the effective TTL: request override → global default. */
-    private resolveTTL;
-    /**
-     * Read a cached value. Fast sync path (memory) with async persistence
-     * fallback for adapters whose `get` returns a Promise.
-     * @param key Cache key (e.g. `"GET /posts?page=1"`).
-     * @returns The cached value, or undefined when absent/expired (the hit is
-     * cleared on expiry so a stale value is never served).
-     */
-    get<T = unknown>(key: string): Promise<T | undefined>;
-    /**
-     * Store a value.
-     * @param key Cache key.
-     * @param value The response payload.
-     * @param ttlOverride Optional TTL override (ms).
-     * @param namespace Optional namespace for group invalidation.
-     */
-    set(key: string, value: unknown, ttlOverride?: number, namespace?: string, tags?: string[]): void;
-    /**
-     * Invalidate entries belonging to a namespace (e.g. a collection name).
-     * Also clears the namespace index entry.
-     */
-    invalidate(namespace: string): void;
-    /** Remove a single key. */
-    delete(key: string): void;
-    /**
-     * Delete every entry whose key starts with `prefix`.
-     *
-     * Useful for fine-grained invalidation, e.g.:
-     * ```ts
-     * client.cache.deleteByPrefix('getList:posts'); // delete all getList cache
-     * client.cache.deleteByPrefix('getOne:posts');  // delete all getOne cache
-     * ```
-     */
-    deleteByPrefix(prefix: string): void;
-    /** Drop every cached entry (memory + persistence). */
-    clear(): void;
-    /** Cache hit/miss/entry statistics. */
-    stats(): {
-        hits: number;
-        misses: number;
-        entries: number;
-    };
-    private persistKey;
-    private readPersisted;
-}
-/** Resolve per-request cache options into a usable directive. */
-declare function resolveCacheDirective(opts?: {
-    cache?: boolean | number | {
-        ttl?: number;
-        key?: string;
-    };
-    ttl?: number;
-}): {
-    enabled: boolean;
-    ttl?: number;
-    key?: string;
-} | null;
-
 declare class HttpClient {
     private baseUrl;
     private authStore;
     private defaultFetch;
-    /** Optional query cache store (wired when the client enables caching). */
-    private cache?;
-    /** Master switch resolved from CacheConfig.enabled. */
-    private cacheEnabled;
     /**
      * Abort controllers for in-flight requests, keyed by their cancellation key
      * (default `METHOD path`). A new request with the same key aborts the
@@ -345,13 +266,6 @@ declare class HttpClient {
      * @param authStore The auth store providing the token for Authorization headers.
      */
     constructor(baseUrl: string, authStore: AuthStore);
-    /**
-     * Attach a cache store + master switch.
-     * Called by the client constructor when cache config is present.
-     */
-    setCache(cache: CacheStore, enabled: boolean): void;
-    /** Whether the global cache flag is on (requests opt in/out individually too). */
-    get cacheIsEnabled(): boolean;
     private refreshAuth;
     /**
      * Globally enable or disable auto-cancellation of duplicated pending requests.
@@ -381,31 +295,12 @@ declare class HttpClient {
      * @throws {ApiError} On non-2xx responses or when the request is aborted
      * (aborted requests throw an `ApiError` with `isAbort === true`).
      */
-    /** Invalidate a namespace (collection name). No-op when cache is off. */
-    invalidateCache(namespace: string): void;
-    /** Current cache statistics (hits/misses/entries), or null when disabled. */
-    cacheStats(): {
-        hits: number;
-        misses: number;
-        entries: number;
-    } | null;
     request<T = unknown>(method: Method, path: string, body?: unknown, options?: RequestOptions): Promise<T | null>;
     /**
-     * Execute the actual HTTP request (fetch + parse + cache). Called by {@link request}
+     * Execute the actual HTTP request (fetch + parse). Called by {@link request}
      * as the inner in-flight unit so single-flight callers can reuse the promise.
      */
     private doRequest;
-    /** Build a token-scoped cache key: `METHOD path|token-hash|params`. */
-    private cacheKeyFor;
-    /** Best-effort namespace (collection name) from a REST path. */
-    private namespaceFromPath;
-    /**
-     * Semantic prefix tags for `deleteByPrefix`, derived from the REST shape:
-     * - `/{collection}?...` → `getList:{collection}`
-     * - `/{collection}/{id}` → `getOne:{collection}`
-     * - `/collections?...` / `/collections/{id}` → `collections:getList` / `collections:getOne`
-     */
-    private cacheTagsFor;
     /**
      * HTTP GET.
      * @param path URL path.
@@ -513,6 +408,37 @@ declare class RealtimeService {
     private clearReconnectTimer;
 }
 
+/** A single field definition as returned by `GET /collections`. */
+interface SchemaField {
+    id?: string;
+    name: string;
+    type: string;
+    required?: boolean;
+    unique?: boolean;
+    options?: {
+        /** For relation fields: the target collection name. */
+        collection?: string;
+        /** Max selectable/related items (multi when > 1). */
+        maxSelect?: number;
+        /** Allowed values for select / multi_select fields. */
+        values?: string[];
+    } & Record<string, unknown>;
+    indexed?: boolean;
+    hidden?: boolean;
+    system?: boolean;
+    sort_order?: number;
+}
+/** A collection definition as returned by `GET /collections`. */
+interface CollectionSchema {
+    id?: string;
+    name: string;
+    type: "base" | "auth";
+    system?: boolean;
+    fields?: SchemaField[];
+    rules?: Record<string, unknown>;
+    options?: Record<string, unknown>;
+}
+
 /**
  * A realtime record-change event delivered to subscription callbacks.
  * Mirrors PocketBase's RealtimeService result shape (`action` + `record`).
@@ -535,9 +461,53 @@ declare class CollectionService<T = ApiRecord> {
     private collectionName;
     private authStore?;
     private realtime?;
+    /** Optional schema for this collection (from client `types.schemas`). */
+    private schema?;
+    /**
+     * Active field projection from {@link select}. `"*"` (or unset) means
+     * "all visible (non-hidden) fields" — resolved against the schema when
+     * one is available, otherwise left to the server.
+     */
+    private fieldsPreset?;
     /** @internal */
-    constructor(http: HttpClient, collectionName: string, authStore?: AuthStore, realtime?: RealtimeService);
+    constructor(http: HttpClient, collectionName: string, authStore?: AuthStore, realtime?: RealtimeService, schema?: CollectionSchema);
     private encodeId;
+    /**
+     * Project list/read responses to the given fields (PocketBase `fields`
+     * param). Field names are type-checked when this service is typed
+     * (codegen / `typed<T>()`).
+     *
+     * Returns a derived service — the original is untouched.
+     *
+     * @example
+     * ```ts
+     * const t = await client.collection("posts").select("id", "title").getList();
+     * // GET /api/posts?fields=id,title
+     *
+     * // All visible fields (hidden fields are excluded server-side)
+     * const all = await client.collection("posts").select("*").getList();
+     * // GET /api/posts?fields=id,title,published,… (schema known)
+     * ```
+     *
+     * When no schema is known, the default (no `select()` call) sends no
+     * `fields` param — the server returns every non-password field.
+     * Pass `select("*")` to restore the default after a projection.
+     */
+    select<K extends FieldKey<T> | "*">(...fields: K[]): CollectionService<T>;
+    /**
+     * Fields to send with reads:
+     * 1. explicit `options.fields` (caller wins)
+     * 2. `select()` preset
+     * 3. schema default — all visible (non-hidden, non-system) fields
+     */
+    private effectiveFields;
+    /**
+     * All non-hidden, non-system, non-password field names from the schema.
+     * `undefined` when no schema is available (server decides).
+     */
+    visibleFields(): string | undefined;
+    /** Warn once when an expand field is not a relation (schema known). */
+    private validateExpand;
     /**
      * Fetch a paginated list of records (PocketBase `getList`).
      *
@@ -545,27 +515,27 @@ declare class CollectionService<T = ApiRecord> {
      * @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>;
+    getList<T2 = T>(page?: number, perPage?: number, options?: ListOptions<T> & 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>>;
+    getFullList<T2 = T>(options?: ListOptions<T> & 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.
      */
-    getFirstListItem<T2 = T>(filter: string, options?: RequestOptions): Promise<T2 | null>;
+    getFirstListItem<T2 = T>(filter: FilterString<T>, options?: ListOptions<T> & RequestOptions): Promise<T2 | null>;
     /**
      * Get a single record by ID.
      * @param id Record ID.
      * @param options Optional request options.
      */
-    getOne(id: string, options?: RequestOptions): Promise<T | null>;
+    getOne(id: string, options?: ReadOptions<T> & RequestOptions): Promise<T | null>;
     /**
      * Create a new record.
      * @param data Record fields. When `T` is a concrete shape (e.g. a generated
@@ -613,6 +583,12 @@ declare class CollectionService<T = ApiRecord> {
      * ```
      */
     typed<TRecord = ApiRecord>(): CollectionService<TRecord>;
+    /**
+     * Explicitly bind a schema for this service (overrides the client-level
+     * `types.schemas`). Enables schema-aware defaults: hidden fields are
+     * excluded from responses, select/expand are validated.
+     */
+    withSchema(schema: CollectionSchema): CollectionService<T>;
     /**
      * Subscribe to realtime changes for this collection.
      * The event's `action` is one of `"create" | "update" | "delete"`.
@@ -812,37 +788,6 @@ declare class CollectionsService {
     unsubscribe(): void;
 }
 
-/** A single field definition as returned by `GET /collections`. */
-interface SchemaField {
-    id?: string;
-    name: string;
-    type: string;
-    required?: boolean;
-    unique?: boolean;
-    options?: {
-        /** For relation fields: the target collection name. */
-        collection?: string;
-        /** Max selectable/related items (multi when > 1). */
-        maxSelect?: number;
-        /** Allowed values for select / multi_select fields. */
-        values?: string[];
-    } & Record<string, unknown>;
-    indexed?: boolean;
-    hidden?: boolean;
-    system?: boolean;
-    sort_order?: number;
-}
-/** A collection definition as returned by `GET /collections`. */
-interface CollectionSchema {
-    id?: string;
-    name: string;
-    type: "base" | "auth";
-    system?: boolean;
-    fields?: SchemaField[];
-    rules?: Record<string, unknown>;
-    options?: Record<string, unknown>;
-}
-
 /** Format a raw collection name into a valid TS identifier (PascalCase). */
 declare function collectionTypeName(name: string): string;
 /**
@@ -882,26 +827,6 @@ declare function fieldTypeKind(field: SchemaField): FieldTypeKind;
  */
 declare function schemaFieldType(field: SchemaField): unknown;
 
-/**
- * Callable cache namespace: `client.cache(config)` configures, and
- * `client.cache.deleteByPrefix(...)` etc. manage cached entries.
- */
-interface CacheController {
-    /** Configure the query cache at runtime. */
-    (config?: CacheConfig): LazypockClient;
-    /** Delete every entry whose key starts with `prefix` (e.g. `getList:posts`). */
-    deleteByPrefix(prefix: string): void;
-    /** Invalidate a collection's cached entries (alias of invalidateCache). */
-    invalidate(namespace: string): void;
-    /** Drop every cached entry. */
-    clear(): void;
-    /** Cache hit/miss/entry stats, or null when never configured. */
-    stats(): {
-        hits: number;
-        misses: number;
-        entries: number;
-    } | null;
-}
 /** Options for constructing a {@link LazypockClient}. */
 interface LazypockClientOptions {
     /** API base URL (e.g. 'http://localhost:4000/api') */
@@ -912,24 +837,6 @@ interface LazypockClientOptions {
     authStore?: AuthStore;
     /** Real-time service for Phoenix Channel WebSocket subscriptions */
     realtime?: RealtimeService;
-    /**
-     * Query cache configuration. Disabled by default.
-     *
-     * ```ts
-     * const client = createClient({
-     *   baseUrl: '...',
-     *   cache: {
-     *     enabled: true,
-     *     defaultTTL: 30_000,
-     *     store: myStorage,      // optional persistence (same interface as auth)
-     *   },
-     * });
-     * ```
-     *
-     * When enabled, readable GETs are cached. Requests can opt out via
-     * `{ cache: false }`, or opt in with a custom TTL via `{ ttl: ms }`.
-     */
-    cache?: CacheConfig;
     /**
      * Optional schema types for generating typed services at runtime.
      * When provided, `collection()` returns a service whose create/update
@@ -963,9 +870,6 @@ declare class LazypockClient {
     readonly files: FilesService;
     private collectionCache;
     private schemaByName?;
-    private cacheStore?;
-    /** Namespace → realtime unsubscribe; used for realtime-driven invalidation. */
-    private realtimeInvalidators;
     /**
      * Create a new Lazypock client.
      * @param options Configuration options.
@@ -982,7 +886,7 @@ declare class LazypockClient {
      * @param name The collection name.
      * @returns A {@link CollectionService} instance.
      */
-    collection(name: string): CollectionService<unknown>;
+    collection(name: string, schema?: CollectionSchema): CollectionService<unknown>;
     /**
      * Get a typed service whose record shape is derived from the schema
      * passed via `options.types.schemas` (if available), or fall back to
@@ -1020,47 +924,6 @@ declare class LazypockClient {
     cancelRequest(requestKey: string): this;
     /** Abort all pending requests. */
     cancelAllRequests(): this;
-    /**
-     * Configure the query cache at runtime (also a namespace for cache
-     * management methods).
-     *
-     * ```ts
-     * client.cache({ enabled: true, defaultTTL: 30_000 });
-     * client.cache.deleteByPrefix('getList:posts');  // all list caches for posts
-     * client.cache.deleteByPrefix('getOne:posts');   // all one-record caches
-     * ```
-     *
-     * When enabled, GET requests cache their payload; mutations invalidate the
-     * affected collection automatically. Individual requests can opt out with
-     * `{ cache: false }` or override the TTL with `{ ttl: ms }`.
-     */
-    readonly cache: CacheController;
-    /**
-     * Drop every cached entry (all collections / namespaces).
-     * Also disables realtime-driven invalidation subscriptions.
-     */
-    clearCache(): this;
-    /**
-     * Invalidate cached entries for a collection (or custom namespace).
-     * Runs automatically on mutations — call explicitly when data changed
-     * out-of-band (e.g. another client wrote to the same collection).
-     */
-    invalidateCache(namespace: string): this;
-    /**
-     * Cache hit/miss/entry statistics.
-     * Returns null when caching was never configured.
-     */
-    cacheStats(): {
-        hits: number;
-        misses: number;
-        entries: number;
-    } | null;
-    /**
-     * Subscribe a collection's cache to realtime invalidation: any inbound
-     * create/update/delete event for the collection clears its cached entries.
-     * Returns an unsubscribe function.
-     */
-    invalidateCacheOnRealtime(collectionName: string): () => void;
     /** Check whether any superuser exists (for login vs setup screen routing). */
     checkSuperuser(): Promise<{
         has_superuser: boolean;
@@ -1153,4 +1016,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 CacheConfig, type CacheRequestOptions, CacheStore, 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, resolveCacheDirective, schemaFieldType, wsUrlFromBaseUrl };
+export { ApiError, type ApiRecord, type AuthModel, AuthStore, type CollectionSchema, CollectionService, type CollectionsMessage, CollectionsService, type CreateData, type ExpandString, type FieldKey, type FileRecord, FilesService, type FilterOp, type FilterString, HttpClient, LazypockClient, type LazypockClientOptions, type LazypockCollections, type ListOptions, type ListResult, type ReadOptions, type RealtimeCallback, type RealtimeMessage, RealtimeService, type RecordShape, type RequestOptions, type SchemaField, type SortString, type StorageAdapter, type SystemFields, TypedClient, type UpdateData, collectionTypeName, createClient, fieldTypeKind, fieldTypeScriptType, generateTypes, getFileUrl, getScaleUrl, getThumbUrl, schemaFieldType, wsUrlFromBaseUrl };