pbtsdb 0.3.0 → 0.5.0

package/dist/index.d.ts

@@ -1,427 +1,9 @@
-import { Collection, InsertMutationFn, UpdateMutationFn, DeleteMutationFn, BaseCollectionConfig } from '@tanstack/db';
+export { CreateCollectionOptions, ExcludeUndefined, ExtractRecordType, ExtractRelations, Logger, OmittableFields, ParseExpandFields, RelationAsCollection, SchemaDeclaration, WithExpand, createCollection, newRecordId, resetLogger, setLogger } from './core.js';
 export { BTreeIndex, BasicIndex, DeltaEvent, DeltaType, EffectConfig, EffectContext, IndexConstructor, ReverseIndex, createEffect, toArray } from '@tanstack/db';
-import PocketBase from 'pocketbase';
-import { Collection as Collection$1 } from '@tanstack/react-db';
-import { QueryCollectionUtils } from '@tanstack/query-db-collection';
-import { QueryClient } from '@tanstack/react-query';
 import React, { ReactNode } from 'react';
-
-/**
- * Base record type required by PocketBase collections.
- * All records must have an 'id' field.
- */
-interface BaseRecord {
-    id: string;
-}
-/**
- * Schema declaration for type-safe collection management.
- * Define your PocketBase collections with their record types and relations.
- *
- * @example
- * ```ts
- * interface MySchema extends SchemaDeclaration {
- *     users: {
- *         type: UserRecord;
- *         relations: {
- *             org: OrgRecord;
- *         };
- *     };
- * }
- * ```
- */
-interface SchemaDeclaration {
-    [collectionName: string]: {
-        type: BaseRecord;
-        relations?: {
-            [fieldName: string]: BaseRecord | BaseRecord[];
-        };
-    };
-}
-/**
- * Extracts the record type from a schema collection.
- * @internal
- */
-type ExtractRecordType<Schema extends SchemaDeclaration, CollectionName extends keyof Schema> = Schema[CollectionName]['type'];
-/**
- * Valid field names that can be omitted during insert operations.
- * Excludes 'id' which is always required for TanStack DB record tracking.
- * @internal
- */
-type OmittableFields<T extends object> = Exclude<keyof T, 'id'>;
-/**
- * Computes the insert input type by making specified fields optional.
- * Used to support omitting server-generated fields (created, updated) during insertion.
- *
- * IMPORTANT: The 'id' field can NEVER be omitted as TanStack DB requires it for record tracking.
- *
- * @example
- * ```ts
- * type BookInsert = ComputeInsertType<Books, ['created', 'updated']>
- * // Result: Omit<Books, 'created' | 'updated'> & Partial<Pick<Books, 'created' | 'updated'>>
- * ```
- * @internal
- */
-type ComputeInsertType<T extends object, OmitFields extends readonly OmittableFields<T>[]> = Omit<T, OmitFields[number]> & Partial<Pick<T, OmitFields[number]>>;
-/**
- * Extracts the relations object from a schema collection.
- * Returns never if the collection has no relations defined.
- * @internal
- */
-type ExtractRelations<Schema extends SchemaDeclaration, CollectionName extends keyof Schema> = Schema[CollectionName] extends {
-    relations: infer R;
-} ? R : never;
-/**
- * Parses comma-separated relation field names into a union type.
- * Recursively processes "field1,field2,field3" into "field1" | "field2" | "field3".
- *
- * @example
- * ParseExpandFields<"customer,address"> => "customer" | "address"
- * @internal
- */
-type ParseExpandFields<T extends string> = T extends `${infer Field},${infer Rest}` ? Field | ParseExpandFields<Rest> : T;
-/**
- * Builds the expand object type based on field names.
- * If expand fields are provided, adds an optional `expand` property with properly typed relations.
- *
- * @example
- * ```ts
- * // Without expand
- * WithExpand<Schema, 'jobs', undefined> => JobRecord
- *
- * // With expand
- * WithExpand<Schema, 'jobs', 'customer'> => JobRecord & {
- *     expand?: { customer?: CustomerRecord }
- * }
- * ```
- */
-type WithExpand<Schema extends SchemaDeclaration, CollectionName extends keyof Schema, ExpandFields extends string | undefined> = ExpandFields extends string ? ExtractRecordType<Schema, CollectionName> & {
-    expand?: {
-        [K in ParseExpandFields<ExpandFields>]?: K extends keyof ExtractRelations<Schema, CollectionName> ? ExtractRelations<Schema, CollectionName>[K] extends Array<infer U> ? U[] : ExtractRelations<Schema, CollectionName>[K] : never;
-    };
-} : ExtractRecordType<Schema, CollectionName>;
-/**
- * Removes undefined from a union type.
- * Used to unwrap optional relation types.
- *
- * @example
- * ExcludeUndefined<Customer | undefined> => Customer
- * @internal
- */
-type ExcludeUndefined<T> = T extends (infer U) | undefined ? U : T;
-/**
- * Converts a schema relation type to its corresponding Collection constraint.
- * Handles both single relations (T) and array relations (T[]).
- * Accepts collections with any insert type to support omitOnInsert configurations.
- *
- * Uses constraint (extends Collection<T, ...>) rather than exact type to allow
- * collections with different TInput types (from omitOnInsert) to be compatible.
- *
- * @example
- * RelationAsCollection<Customer> => Collection<Customer, string | number, any, any, any>
- * RelationAsCollection<Customer[]> => Collection<Customer, string | number, any, any, any>
- * @internal
- */
-type RelationAsCollection<T> = T extends Array<infer U> ? U extends object ? Collection<U, string | number, any, any, any> : Collection<object, string | number, any, any, any> : T extends object ? Collection<T, string | number, any, any, any> : Collection<object, string | number, any, any, any>;
-/**
- * Configuration for per-collection expand - maps relation field names to their target collections.
- * Relations configured here are automatically expanded on every fetch and auto-upserted into target collections.
- *
- * @example
- * ```ts
- * const authorsCollection = createCollection<Schema>(pb, queryClient)('authors');
- * const booksCollection = createCollection<Schema>(pb, queryClient)('books', {
- *     expand: {
- *         author: authorsCollection  // Always expand 'author', upsert into authorsCollection
- *     }
- * });
- * ```
- */
-type ExpandConfig<Schema extends SchemaDeclaration, CollectionName extends keyof Schema> = ExtractRelations<Schema, CollectionName> extends never ? Record<string, never> : Partial<{
-    [K in keyof ExtractRelations<Schema, CollectionName>]: RelationAsCollection<ExcludeUndefined<ExtractRelations<Schema, CollectionName>[K]>>;
-}>;
-/**
- * Options for creating a collection.
- */
-interface CreateCollectionOptions<Schema extends SchemaDeclaration, CollectionName extends keyof Schema> {
-    /**
-     * Configure relations to automatically expand on every fetch.
-     * Maps relation field names to their target collections for auto-upsert.
-     *
-     * Expanded records are automatically inserted into their target collections.
-     *
-     * @example
-     * ```ts
-     * const authorsCollection = createCollection<Schema>(pb, queryClient)('authors');
-     * const booksCollection = createCollection<Schema>(pb, queryClient)('books', {
-     *     expand: {
-     *         author: authorsCollection  // Always expand, auto-upsert into authorsCollection
-     *     }
-     * });
-     *
-     * // Expand is automatic - no .expand() call needed
-     * const { data } = useLiveQuery((q) => q.from({ books: booksCollection }));
-     * // data[0].expand.author is typed and populated
-     * ```
-     */
-    expand?: ExpandConfig<Schema, CollectionName>;
-    /**
-     * Fields that can be omitted during insert operations.
-     * Useful for server-generated fields like 'created', 'updated'.
-     *
-     * When specified, the insert() method will accept records without these fields,
-     * and the omitted fields become optional in the insert input type.
-     *
-     * **Type safety:** Only valid field names from the record type are accepted.
-     * **IMPORTANT:** The 'id' field can NEVER be omitted as TanStack DB requires it.
-     *
-     * @example
-     * ```ts
-     * // Allow inserting without created, updated (server-generated timestamps)
-     * const booksCollection = createCollection<Schema>(pb, queryClient)('books', {
-     *     omitOnInsert: ['created', 'updated'] as const
-     * });
-     *
-     * // Now insert() accepts records without those fields
-     * booksCollection.insert({
-     *     id: newRecordId(),  // id is always required
-     *     title: 'New Book',
-     *     isbn: '1234567890',
-     *     genre: 'Fiction',
-     *     author: authorId
-     *     // created, updated are optional
-     * });
-     * ```
-     */
-    omitOnInsert?: readonly OmittableFields<ExtractRecordType<Schema, CollectionName>>[];
-    /**
-     * Custom handler for insert mutations.
-     *
-     * **Default behavior (not provided):** Automatically creates records in PocketBase,
-     * excluding auto-generated fields (id, created, updated, collectionId, collectionName).
-     *
-     * **Custom handler:** Provide your own handler to customize insert behavior.
-     *
-     * **Disable:** Set to `false` to disable insert mutations entirely (will throw error if insert is called).
-     *
-     * @example
-     * ```ts
-     * // Use default automatic handler (recommended)
-     * const collection = createCollection<Schema>(pb, queryClient)('books');
-     *
-     * // Custom handler
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
-     *     onInsert: async ({ transaction }) => {
-     *         for (const mutation of transaction.mutations) {
-     *             await customInsertLogic(mutation.modified);
-     *         }
-     *         await queryClient.invalidateQueries({ queryKey: ['books'] });
-     *     }
-     * });
-     *
-     * // Disable inserts (read-only collection)
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
-     *     onInsert: false
-     * });
-     * ```
-     */
-    onInsert?: InsertMutationFn<ExtractRecordType<Schema, CollectionName>> | false;
-    /**
-     * Custom handler for update mutations.
-     *
-     * **Default behavior (not provided):** Automatically updates records in PocketBase
-     * with the changed fields.
-     *
-     * **Custom handler:** Provide your own handler to customize update behavior.
-     *
-     * **Disable:** Set to `false` to disable update mutations entirely (will throw error if update is called).
-     *
-     * @example
-     * ```ts
-     * // Use default automatic handler (recommended)
-     * const collection = createCollection<Schema>(pb, queryClient)('books');
-     *
-     * // Custom handler
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
-     *     onUpdate: async ({ transaction }) => {
-     *         for (const mutation of transaction.mutations) {
-     *             await customUpdateLogic(mutation.original.id, mutation.changes);
-     *         }
-     *         await queryClient.invalidateQueries({ queryKey: ['books'] });
-     *     }
-     * });
-     *
-     * // Disable updates (read-only collection)
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
-     *     onUpdate: false
-     * });
-     * ```
-     */
-    onUpdate?: UpdateMutationFn<ExtractRecordType<Schema, CollectionName>> | false;
-    /**
-     * Custom handler for delete mutations.
-     *
-     * **Default behavior (not provided):** Automatically deletes records from PocketBase.
-     *
-     * **Custom handler:** Provide your own handler to customize delete behavior.
-     *
-     * **Disable:** Set to `false` to disable delete mutations entirely (will throw error if delete is called).
-     *
-     * @example
-     * ```ts
-     * // Use default automatic handler (recommended)
-     * const collection = createCollection<Schema>(pb, queryClient)('books');
-     *
-     * // Custom handler
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
-     *     onDelete: async ({ transaction }) => {
-     *         for (const mutation of transaction.mutations) {
-     *             await customDeleteLogic(mutation.original.id);
-     *         }
-     *         await queryClient.invalidateQueries({ queryKey: ['books'] });
-     *     }
-     * });
-     *
-     * // Disable deletes (read-only collection)
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
-     *     onDelete: false
-     * });
-     * ```
-     */
-    onDelete?: DeleteMutationFn<ExtractRecordType<Schema, CollectionName>> | false;
-    /**
-     * Sync mode for the collection. Controls when and how data is fetched from PocketBase.
-     *
-     * - `'eager'` (default): Fetches all data immediately when collection is created.
-     *   Queries are evaluated client-side against the cached data. Fast for small datasets
-     *   but loads entire collection into memory. Matches TanStack DB default.
-     *
-     * - `'on-demand'`: Fetches data only when queries execute. Each query with different
-     *   filters/sorting triggers a new fetch from PocketBase. Enables true server-side
-     *   filtering and is better for large datasets.
-     *
-     * @default 'eager'
-     *
-     * @example
-     * ```ts
-     * // Default: eager mode - client-side filtering
-     * const collection = createCollection<Schema>(pb, queryClient)('books');
-     *
-     * // On-demand mode - server-side filtering
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
-     *     syncMode: 'on-demand'
-     * });
-     * ```
-     */
-    syncMode?: 'eager' | 'on-demand';
-    /**
-     * Whether to ignore PocketBase auto-cancellation errors.
-     *
-     * PocketBase automatically cancels pending requests when a new request is made
-     * to the same endpoint. This can throw ClientResponseError with a message
-     * containing "autocancelled". When this option is true, such errors are
-     * silently ignored and the existing cached data is returned for the cancelled request.
-     *
-     * @default true
-     *
-     * @example
-     * ```ts
-     * // Default: auto-cancellation errors are ignored
-     * const collection = createCollection<Schema>(pb, queryClient)('books');
-     *
-     * // Explicitly handle auto-cancellation errors
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
-     *     ignoreAutoCancellation: false
-     * });
-     * ```
-     */
-    ignoreAutoCancellation?: boolean;
-    /**
-     * Additional options passed directly to the underlying TanStack DB collection.
-     * Use this to configure indexing, garbage collection, comparison functions,
-     * and any other TanStack DB collection options not explicitly exposed by pbtsdb.
-     *
-     * Options set here are spread into the `queryCollectionOptions()` call.
-     * Fields managed by pbtsdb (`getKey`, `syncMode`, `onInsert`, `onUpdate`,
-     * `onDelete`, `schema`) are excluded from the type.
-     *
-     * @example
-     * ```ts
-     * import { BasicIndex } from 'pbtsdb'
-     * const collection = createCollection<Schema>(pb, queryClient)('books', {
-     *     collectionOptions: {
-     *         autoIndex: 'eager',
-     *         defaultIndexType: BasicIndex,
-     *         gcTime: 60000,
-     *     }
-     * });
-     * ```
-     */
-    collectionOptions?: Omit<Partial<BaseCollectionConfig<ExtractRecordType<Schema, CollectionName>, string | number>>, 'getKey' | 'syncMode' | 'onInsert' | 'onUpdate' | 'onDelete' | 'schema'>;
-}
-
-/**
- * Compute the record type with expand property when expand option is configured.
- * @internal
- */
-type WithExpandFromConfig<Schema extends SchemaDeclaration, C extends keyof Schema, Opts> = Opts extends {
-    expand: infer E;
-} ? ExtractRecordType<Schema, C> & {
-    expand?: {
-        [K in keyof E]: K extends keyof ExtractRelations<Schema, C> ? ExtractRelations<Schema, C>[K] extends Array<infer U> ? U[] : ExtractRelations<Schema, C>[K] : never;
-    };
-} : ExtractRecordType<Schema, C>;
-/**
- * Subscription helpers added to collection instances.
- * @internal
- */
-interface CollectionSubscriptionHelpers {
-    /** The PocketBase collection name */
-    collectionName: string;
-    /** Wait for subscription to be established (useful in tests) */
-    waitForSubscription: (timeout?: number) => Promise<void>;
-    /** Check if collection has an active subscription */
-    isSubscribed: () => boolean;
-}
-/**
- * Inferred collection type from config options.
- * @internal
- */
-type InferCollectionType<Schema extends SchemaDeclaration, C extends keyof Schema, Opts extends CreateCollectionOptions<Schema, C>> = Collection$1<WithExpandFromConfig<Schema, C, Opts>, string | number, QueryCollectionUtils<WithExpandFromConfig<Schema, C, Opts>, string | number, WithExpandFromConfig<Schema, C, Opts>>, never, Opts extends {
-    omitOnInsert: infer O extends readonly OmittableFields<ExtractRecordType<Schema, C>>[];
-} ? ComputeInsertType<ExtractRecordType<Schema, C>, O> : ExtractRecordType<Schema, C>> & CollectionSubscriptionHelpers;
-/**
- * Creates a type-safe TanStack DB collection backed by PocketBase.
- * Use this when you need fine-grained control or need to create collections with dependencies.
- *
- * @param pb - PocketBase client instance
- * @param queryClient - TanStack Query client
- * @returns A curried function that takes collection name and options
- *
- * @example
- * Basic usage:
- * ```ts
- * const booksCollection = createCollection<Schema>(pb, queryClient)('books', {});
- *
- * // Use directly
- * const books = await booksCollection.getFullList();
- * ```
- *
- * @example
- * With auto-expand relations:
- * ```ts
- * const authorsCollection = createCollection<Schema>(pb, queryClient)('authors', {});
- * const booksCollection = createCollection<Schema>(pb, queryClient)('books', {
- *     expand: {
- *         author: authorsCollection  // Always expand, auto-upsert into authorsCollection
- *     }
- * });
- *
- * // Expand is automatic - no .expand() call needed
- * const { data } = useLiveQuery((q) => q.from({ books: booksCollection }));
- * // data[0].expand.author is typed and populated
- * ```
- */
-declare function createCollection<Schema extends SchemaDeclaration>(pb: PocketBase, queryClient: QueryClient): <C extends keyof Schema & string, Opts extends CreateCollectionOptions<Schema, C> = CreateCollectionOptions<Schema, C>>(collectionName: C, options?: Opts) => InferCollectionType<Schema, C, Opts>;
+import 'pocketbase';
+import '@tanstack/query-db-collection';
+import '@tanstack/react-query';
 
 /**
  * UseStore hook type for variadic collection access.
@@ -547,86 +129,4 @@ interface ReactProviderResult<CollectionsMap> {
  */
 declare function createReactProvider<CollectionsMap extends Record<string, any>>(collections: CollectionsMap): ReactProviderResult<CollectionsMap>;
 
-/**
- * Logger interface for subscription events and internal operations.
- * Users can provide their own implementation to integrate with external logging services.
- */
-interface Logger {
-    /**
-     * Log debug-level messages (typically only shown in development).
-     * @param msg - The message to log
-     * @param context - Optional context object with additional information
-     */
-    debug: (msg: string, context?: object) => void;
-    /**
-     * Log info-level messages.
-     * @param msg - The message to log
-     * @param context - Optional context object with additional information
-     */
-    info: (msg: string, context?: object) => void;
-    /**
-     * Log warning-level messages.
-     * @param msg - The message to log
-     * @param context - Optional context object with additional information
-     */
-    warn: (msg: string, context?: object) => void;
-    /**
-     * Log error-level messages.
-     * @param msg - The message to log
-     * @param context - Optional context object with additional information
-     */
-    error: (msg: string, context?: object) => void;
-}
-/**
- * Set a custom logger implementation.
- * This allows users to integrate with their own logging services (e.g., Sentry, LogRocket, etc.).
- *
- * @param customLogger - The custom logger implementation
- *
- * @example
- * ```ts
- * import { setLogger } from 'pbtsdb';
- *
- * // Integration with a custom logging service
- * setLogger({
- *     debug: (msg, context) => myLogger.debug(msg, context),
- *     warn: (msg, context) => myLogger.warn(msg, context),
- *     error: (msg, context) => {
- *         myLogger.error(msg, context);
- *         Sentry.captureMessage(msg, { level: 'error', extra: context });
- *     },
- * });
- * ```
- *
- * @example
- * ```ts
- * // Disable all logging
- * setLogger({
- *     debug: () => {},
- *     warn: () => {},
- *     error: () => {},
- * });
- * ```
- */
-declare function setLogger(customLogger: Logger): void;
-/**
- * Reset the logger to the default implementation.
- */
-declare function resetLogger(): void;
-
-/**
- * Generates a new PocketBase-compatible record ID.
- * Returns a 15-character alphanumeric string (lowercase letters and numbers).
- *
- * PocketBase uses 15-character IDs for records, formatted as lowercase alphanumeric.
- *
- * @returns A 15-character alphanumeric string suitable for use as a PocketBase record ID
- *
- * @example
- * ```ts
- * const id = newRecordId(); // "a1b2c3d4e5f6g7h"
- * ```
- */
-declare function newRecordId(): string;
-
-export { type CreateCollectionOptions, type ExcludeUndefined, type ExtractRecordType, type ExtractRelations, type Logger, type OmittableFields, type ParseExpandFields, type ReactProviderResult, type RelationAsCollection, type SchemaDeclaration, type WithExpand, createCollection, createReactProvider, newRecordId, resetLogger, setLogger };
+export { type ReactProviderResult, createReactProvider };