pbtsdb 0.3.0 → 0.4.0

package/dist/core.d.ts

@@ -0,0 +1,506 @@
+import { Collection, InsertMutationFn, UpdateMutationFn, DeleteMutationFn, BaseCollectionConfig } from '@tanstack/db';
+export { BTreeIndex, BasicIndex, DeltaEvent, DeltaType, EffectConfig, EffectContext, IndexConstructor, ReverseIndex, createEffect, toArray } from '@tanstack/db';
+import PocketBase from 'pocketbase';
+import { QueryCollectionUtils } from '@tanstack/query-db-collection';
+import { QueryClient } from '@tanstack/react-query';
+
+/**
+ * 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<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>;
+
+/**
+ * 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 RelationAsCollection, type SchemaDeclaration, type WithExpand, createCollection, newRecordId, resetLogger, setLogger };

package/dist/core.js

@@ -0,0 +1,3 @@
+export { BTreeIndex, BasicIndex, ReverseIndex, createCollection, createEffect, newRecordId, resetLogger, setLogger, toArray } from './chunk-B3RODB7I.js';
+//# sourceMappingURL=core.js.map
+//# sourceMappingURL=core.js.map

package/dist/core.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"core.js"}