pbtsdb 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,614 @@
+import PocketBase, { UnsubscribeFunc } from 'pocketbase';
+import { Collection } from '@tanstack/db';
+import { QueryClient } from '@tanstack/react-query';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+
+/**
+ * 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: object;
+        relations?: {
+            [fieldName: string]: object | object[];
+        };
+    };
+}
+/**
+ * PocketBase real-time event structure.
+ * Matches RecordSubscription from the PocketBase SDK.
+ */
+interface RealtimeEvent<T extends object = object> {
+    action: string;
+    record: T;
+}
+/**
+ * Internal state tracking for subscription management.
+ * Includes reconnection logic and record-specific subscriptions.
+ */
+interface SubscriptionState {
+    unsubscribe: UnsubscribeFunc;
+    recordId?: string;
+    reconnectAttempts: number;
+    isReconnecting: boolean;
+}
+/**
+ * Enhanced collection interface with subscription management capabilities.
+ * Provides methods to control real-time updates from PocketBase.
+ */
+interface SubscribableCollection<T extends object = object> {
+    /**
+     * Subscribe to real-time updates for this collection.
+     * @param recordId - Optional: Subscribe to a specific record, or omit for collection-wide updates
+     */
+    subscribe: (recordId?: string) => Promise<void>;
+    /**
+     * Unsubscribe from real-time updates.
+     * @param recordId - Optional: Unsubscribe from a specific record, or omit for collection-wide
+     */
+    unsubscribe: (recordId?: string) => void;
+    /**
+     * Unsubscribe from all subscriptions for this collection.
+     */
+    unsubscribeAll: () => void;
+    /**
+     * Check if currently subscribed to updates.
+     * @param recordId - Optional: Check a specific record subscription, or omit for collection-wide
+     */
+    isSubscribed: (recordId?: string) => boolean;
+    /**
+     * Wait for a subscription to be fully established (useful for testing).
+     * @param recordId - Optional record ID
+     * @param timeoutMs - Timeout in milliseconds (default: 5000)
+     */
+    waitForSubscription: (recordId?: string, timeoutMs?: number) => Promise<void>;
+}
+/**
+ * Join helper for type-safe TanStack DB joins.
+ * Provides access to pre-configured relation collections.
+ */
+interface JoinHelper<Schema extends SchemaDeclaration, CollectionName extends keyof Schema, RecordType extends object> {
+    /**
+     * Get a pre-configured collection for joining a relation field.
+     * This returns the related collection that can be used with TanStack DB's .join() method.
+     *
+     * @param fieldName - The relation field name to join
+     * @returns The collection for the related entity, or undefined if not configured
+     *
+     * @example
+     * ```ts
+     * const jobsCollection = factory.create('jobs', {
+     *     relations: {
+     *         customer: customersCollection,
+     *         address: addressesCollection
+     *     }
+     * });
+     *
+     * // Use with TanStack DB joins
+     * const query = q.from({ job: jobsCollection })
+     *     .join(
+     *         { customer: jobsCollection.relations.customer },
+     *         ({ job, customer }) => eq(job.customer, customer.id),
+     *         'left'
+     *     );
+     * ```
+     */
+    relations: RelationsConfig<Schema, CollectionName>;
+}
+/**
+ * Extracts the record type from a schema collection.
+ * @internal
+ */
+type ExtractRecordType<Schema extends SchemaDeclaration, CollectionName extends keyof Schema> = Schema[CollectionName]['type'];
+/**
+ * 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;
+/**
+ * Extracts expandable field names from a schema collection.
+ * Returns the union of all relation field names that can be expanded.
+ * @internal
+ */
+type ExpandableFields<Schema extends SchemaDeclaration, CollectionName extends keyof Schema> = ExtractRelations<Schema, CollectionName> extends never ? never : keyof ExtractRelations<Schema, CollectionName> & string;
+/**
+ * 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
+ * NonNullable<Customer | undefined> => Customer
+ * @internal
+ */
+type NonNullable<T> = T extends (infer U) | undefined ? U : T;
+/**
+ * Converts a schema relation type to its corresponding Collection type.
+ * Handles both single relations (T) and array relations (T[]).
+ *
+ * @example
+ * RelationAsCollection<Customer> => Collection<Customer>
+ * RelationAsCollection<Customer[]> => Collection<Customer>
+ * @internal
+ */
+type RelationAsCollection<T> = T extends Array<infer U> ? U extends object ? Collection<U> : Collection<object> : T extends object ? Collection<T> : Collection<object>;
+/**
+ * Configuration for relations - maps field names to their TanStack DB collections.
+ * Used to provide pre-configured collections for manual joins.
+ *
+ * @example
+ * ```ts
+ * const config: RelationsConfig<Schema, 'jobs'> = {
+ *     customer: customersCollection,
+ *     address: addressesCollection
+ * };
+ * ```
+ */
+type RelationsConfig<Schema extends SchemaDeclaration, CollectionName extends keyof Schema> = ExtractRelations<Schema, CollectionName> extends never ? Record<string, never> : Partial<{
+    [K in keyof ExtractRelations<Schema, CollectionName>]: RelationAsCollection<NonNullable<ExtractRelations<Schema, CollectionName>[K]>>;
+}>;
+/**
+ * Options for creating a collection with optional expand and relations.
+ */
+interface CreateCollectionOptions<Schema extends SchemaDeclaration, CollectionName extends keyof Schema, Expand extends string | undefined = undefined> {
+    /**
+     * Pre-configured relation collections for manual TanStack DB joins.
+     *
+     * @example
+     * ```ts
+     * const jobsCollection = factory.create('jobs', {
+     *     relations: {
+     *         customer: customersCollection,
+     *         address: addressesCollection
+     *     }
+     * });
+     * ```
+     */
+    relations?: RelationsConfig<Schema, CollectionName>;
+    /**
+     * Relation fields to auto-expand from PocketBase.
+     * Can be a single field or comma-separated list.
+     * For best type inference, use `as const` when providing comma-separated strings.
+     *
+     * @example
+     * ```ts
+     * // Single relation
+     * const jobsCollection = factory.create('jobs', {
+     *     expand: 'customer'  // Type inference works automatically
+     * });
+     *
+     * // Multiple relations with type inference
+     * const jobsCollection = factory.create('jobs', {
+     *     expand: 'customer,address' as const  // `as const` gives proper typing
+     * });
+     * ```
+     */
+    expand?: Expand;
+    /**
+     * Whether to automatically sync (fetch) data when the collection is created.
+     * Default: false (lazy - sync starts after first query becomes active).
+     *
+     * @example
+     * ```ts
+     * // Lazy loading (default) - sync starts after query
+     * const jobsCollection = factory.create('jobs');
+     * // or explicitly:
+     * const jobsCollection = factory.create('jobs', { startSync: false });
+     *
+     * // Eager loading - sync starts immediately on creation
+     * const jobsCollection = factory.create('jobs', {
+     *     startSync: true
+     * });
+     * ```
+     */
+    startSync?: boolean;
+}
+
+/**
+ * Map of collection names to TanStack DB Collection instances.
+ * Keys are user-defined strings, values are Collection instances.
+ *
+ * @example
+ * ```ts
+ * const stores = {
+ *     jobs: jobsCollection,
+ *     customers: customersCollection,
+ *     addresses: addressesCollection
+ * };
+ * ```
+ */
+type CollectionsMap = Record<string, Collection<any>>;
+/**
+ * Props for the CollectionsProvider component.
+ */
+interface CollectionsProviderProps {
+    /** Map of collection name to Collection instance */
+    collections: CollectionsMap;
+    /** React children to render */
+    children: ReactNode;
+}
+/**
+ * Provider component that makes collections available to all child components.
+ * Wrap your app with this provider to use the useStore and useStores hooks.
+ *
+ * @example
+ * ```tsx
+ * const factory = new CollectionFactory<Schema>(pb, queryClient);
+ * const collections = {
+ *     jobs: factory.create('jobs'),
+ *     customers: factory.create('customers'),
+ *     addresses: factory.create('addresses')
+ * };
+ *
+ * function App() {
+ *     return (
+ *         <CollectionsProvider collections={collections}>
+ *             <YourApp />
+ *         </CollectionsProvider>
+ *     );
+ * }
+ * ```
+ */
+declare function CollectionsProvider({ collections, children }: CollectionsProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Hook to access a single collection from the provider.
+ * Returns the Collection instance for the specified key.
+ *
+ * @template T - The record type for the collection
+ * @param key - The collection key as defined in the provider
+ * @returns The Collection instance
+ * @throws Error if used outside of CollectionsProvider or if key doesn't exist
+ *
+ * @example
+ * ```tsx
+ * function JobsList() {
+ *     const jobsCollection = useStore<JobsRecord>('jobs');
+ *
+ *     const { data } = useLiveQuery((q) =>
+ *         q.from({ jobs: jobsCollection })
+ *     );
+ *
+ *     return (
+ *         <ul>
+ *             {data?.map(job => <li key={job.id}>{job.name}</li>)}
+ *         </ul>
+ *     );
+ * }
+ * ```
+ */
+declare function useStore<T extends object = object>(key: string): Collection<T>;
+/**
+ * Hook to access multiple collections from the provider.
+ * Returns an array of Collection instances matching the order of the keys array.
+ *
+ * @template T - Tuple type of record types for each collection
+ * @param keys - Array of collection keys as defined in the provider
+ * @returns Array of Collection instances in the same order as keys
+ * @throws Error if used outside of CollectionsProvider or if any key doesn't exist
+ *
+ * @example
+ * ```tsx
+ * function JobsWithCustomers() {
+ *     const [jobsCollection, customersCollection] = useStores<
+ *         [JobsRecord, CustomersRecord]
+ *     >(['jobs', 'customers']);
+ *
+ *     const { data } = useLiveQuery((q) =>
+ *         q.from({ job: jobsCollection })
+ *          .join(
+ *              { customer: customersCollection },
+ *              ({ job, customer }) => eq(job.customer, customer.id),
+ *              'left'
+ *          )
+ *     );
+ *
+ *     return <div>...</div>;
+ * }
+ * ```
+ */
+declare function useStores<T extends readonly object[]>(keys: readonly string[]): {
+    [K in keyof T]: Collection<T[K]>;
+};
+
+/**
+ * Factory for creating type-safe TanStack DB collections backed by PocketBase.
+ * Integrates real-time subscriptions with automatic synchronization.
+ */
+declare class CollectionFactory<Schema extends SchemaDeclaration, TMaxDepth extends 0 | 1 | 2 | 3 | 4 | 5 | 6 = 2> {
+    pocketbase: PocketBase;
+    queryClient: QueryClient;
+    private subscriptionManager;
+    constructor(pocketbase: PocketBase, queryClient: QueryClient);
+    /**
+     * Setup automatic subscription lifecycle management.
+     * Hooks into TanStack DB's subscriber events to manage real-time subscriptions.
+     */
+    private setupSubscriptionLifecycle;
+    /**
+     * Create a TanStack DB collection from a PocketBase collection.
+     *
+     * Collections are lazy by default - they don't fetch data or subscribe until queried.
+     * Real-time subscriptions automatically start when the first query becomes active
+     * and stop when the last query unmounts (with a cleanup delay to prevent thrashing).
+     *
+     * @param collection - The name of the collection
+     * @param options - Optional configuration including relations and expand
+     *
+     * @example
+     * Basic usage with automatic lifecycle management:
+     * ```ts
+     * const jobsCollection = factory.create('jobs');
+     *
+     * // In your component - subscription starts automatically
+     * const { data } = useLiveQuery((q) =>
+     *     q.from({ jobs: jobsCollection })
+     * );
+     * // Subscription stops automatically when component unmounts
+     * ```
+     *
+     * @example
+     * With query operators (filters, sorting):
+     * ```ts
+     * const jobsCollection = factory.create('jobs');
+     *
+     * // In your component:
+     * const { data } = useLiveQuery((q) =>
+     *     q.from({ jobs: jobsCollection })
+     *      .where(({ jobs }) => and(
+     *          eq(jobs.status, 'ACTIVE'),
+     *          gt(jobs.created, new Date('2025-01-01'))
+     *      ))
+     *      .orderBy(({ jobs }) => jobs.created, 'desc')
+     * );
+     * ```
+     *
+     * @example
+     * With relation expansion:
+     * ```ts
+     * const jobsCollection = factory.create('jobs', {
+     *     expand: 'customer,location'
+     * });
+     *
+     * // Expanded relations available in record.expand
+     * ```
+     *
+     * @example
+     * With relations (for manual joins):
+     * ```ts
+     * const customersCollection = factory.create('customers');
+     * const jobsCollection = factory.create('jobs', {
+     *     relations: { customer: customersCollection }
+     * });
+     *
+     * // In your component, manually build joins:
+     * const { data } = useLiveQuery((q) =>
+     *     q.from({ job: jobsCollection })
+     *      .join(
+     *          { customer: customersCollection },
+     *          ({ job, customer }) => eq(job.customer, customer.id),
+     *          "left"
+     *      )
+     *      .select(({ job, customer }) => ({
+     *          ...job,
+     *          expand: {
+     *              customer: customer ? { ...customer } : undefined
+     *          }
+     *      }))
+     * );
+     * ```
+     *
+     * @example
+     * Manual subscription control (advanced):
+     * ```ts
+     * const jobsCollection = factory.create('jobs');
+     *
+     * // Manually subscribe to specific record (bypasses automatic lifecycle)
+     * await jobsCollection.subscribe('record_id_123');
+     *
+     * // Check subscription status
+     * const isSubbed = jobsCollection.isSubscribed('record_id_123');
+     *
+     * // Manually unsubscribe
+     * jobsCollection.unsubscribe('record_id_123');
+     * ```
+     */
+    create<C extends keyof Schema & string, E extends string | undefined = undefined>(collection: C, options?: CreateCollectionOptions<Schema, C, E>): Collection<WithExpand<Schema, C, E>> & SubscribableCollection<WithExpand<Schema, C, E>> & JoinHelper<Schema, C, WithExpand<Schema, C, E>>;
+}
+
+declare const SUBSCRIPTION_CONFIG: {
+    readonly MAX_RECONNECT_ATTEMPTS: 5;
+    readonly BASE_RECONNECT_DELAY_MS: 1000;
+    readonly DEFAULT_WAIT_TIMEOUT_MS: 5000;
+    readonly CLEANUP_DELAY_MS: 5000;
+};
+/**
+ * Manages real-time subscriptions to PocketBase collections.
+ * Handles subscription lifecycle, reconnection with exponential backoff,
+ * and automatic synchronization with TanStack DB collections.
+ *
+ * Subscriptions are automatically managed based on TanStack DB's subscriber count:
+ * - Start subscribing when first query becomes active
+ * - Stop subscribing when last query becomes inactive (with cleanup delay)
+ */
+declare class SubscriptionManager {
+    private pocketbase;
+    private subscriptions;
+    private subscriptionPromises;
+    private cleanupTimers;
+    private subscriberCounts;
+    constructor(pocketbase: PocketBase);
+    private setupSubscription;
+    private handleReconnection;
+    /**
+     * Subscribe to real-time updates for a collection.
+     * Returns a promise that resolves when the subscription is fully established.
+     *
+     * @param collectionName - The PocketBase collection name
+     * @param collection - The TanStack DB collection to sync with
+     * @param recordId - Optional: Subscribe to specific record, or omit for collection-wide updates
+     */
+    subscribe<T extends object>(collectionName: string, collection: Collection<T>, recordId?: string): Promise<void>;
+    /**
+     * Unsubscribe from real-time updates.
+     *
+     * @param collectionName - The PocketBase collection name
+     * @param recordId - Optional: Unsubscribe from specific record, or omit for collection-wide
+     */
+    unsubscribe(collectionName: string, recordId?: string): void;
+    /**
+     * Unsubscribe from all subscriptions for a collection.
+     *
+     * @param collectionName - The PocketBase collection name
+     */
+    unsubscribeAll(collectionName: string): void;
+    /**
+     * Check if subscribed to a collection.
+     *
+     * @param collectionName - The PocketBase collection name
+     * @param recordId - Optional: Check specific record subscription, or omit for collection-wide
+     */
+    isSubscribed(collectionName: string, recordId?: string): boolean;
+    /**
+     * Wait for a subscription to be fully established (useful for testing).
+     *
+     * @param collectionName - The collection name
+     * @param recordId - Optional specific record ID
+     * @param timeoutMs - Timeout in milliseconds
+     */
+    waitForSubscription(collectionName: string, recordId?: string, timeoutMs?: number): Promise<void>;
+    /**
+     * Track subscriber addition for a collection.
+     * Automatically subscribes when first subscriber is added.
+     *
+     * @param collectionName - The PocketBase collection name
+     * @param collection - The TanStack DB collection to sync with
+     */
+    addSubscriber<T extends object>(collectionName: string, collection: Collection<T>): Promise<void>;
+    /**
+     * Track subscriber removal for a collection.
+     * Automatically unsubscribes (with delay) when last subscriber is removed.
+     *
+     * @param collectionName - The PocketBase collection name
+     */
+    removeSubscriber(collectionName: string): void;
+    /**
+     * Get the current subscriber count for a collection.
+     * Useful for debugging and testing.
+     *
+     * @param collectionName - The PocketBase collection name
+     * @returns Current subscriber count
+     */
+    getSubscriberCount(collectionName: string): number;
+}
+
+/**
+ * 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 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 'pocketbase-tanstack-db';
+ *
+ * // Example: 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);
+ *         // Also send to error tracking service
+ *         Sentry.captureMessage(msg, { level: 'error', extra: context });
+ *     },
+ * });
+ * ```
+ *
+ * @example
+ * ```ts
+ * // Example: Disable all logging
+ * setLogger({
+ *     debug: () => {},
+ *     warn: () => {},
+ *     error: () => {},
+ * });
+ * ```
+ */
+declare function setLogger(customLogger: Logger): void;
+/**
+ * Reset the logger to the default implementation.
+ */
+declare function resetLogger(): void;
+
+export { CollectionFactory, type CollectionsMap, CollectionsProvider, type CollectionsProviderProps, type CreateCollectionOptions, type ExpandableFields, type ExtractRecordType, type ExtractRelations, type JoinHelper, type Logger, type NonNullable, type ParseExpandFields, type RealtimeEvent, type RelationAsCollection, type RelationsConfig, SUBSCRIPTION_CONFIG, type SchemaDeclaration, type SubscribableCollection, SubscriptionManager, type SubscriptionState, type WithExpand, resetLogger, setLogger, useStore, useStores };