pbtsdb 0.0.1 → 0.1.0

package/dist/index.d.ts

@@ -1,9 +1,17 @@
-import PocketBase, { UnsubscribeFunc } from 'pocketbase';
-import { Collection } from '@tanstack/db';
+import { Collection, InsertMutationFn, UpdateMutationFn, DeleteMutationFn } 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 * as react_jsx_runtime from 'react/jsx-runtime';
-import { ReactNode } from 'react';
+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.
@@ -22,98 +30,37 @@ import { ReactNode } from 'react';
  */
 interface SchemaDeclaration {
     [collectionName: string]: {
-        type: object;
+        type: BaseRecord;
         relations?: {
-            [fieldName: string]: object | object[];
+            [fieldName: string]: BaseRecord | BaseRecord[];
         };
     };
 }
 /**
- * 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.
+ * Extracts the record type from a schema collection.
+ * @internal
  */
-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>;
-}
+type ExtractRecordType<Schema extends SchemaDeclaration, CollectionName extends keyof Schema> = Schema[CollectionName]['type'];
 /**
- * Join helper for type-safe TanStack DB joins.
- * Provides access to pre-configured relation collections.
+ * Valid field names that can be omitted during insert operations.
+ * Excludes 'id' which is always required for TanStack DB record tracking.
+ * @internal
  */
-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>;
-}
+type OmittableFields<T extends object> = Exclude<keyof T, 'id'>;
 /**
- * Extracts the record type from a schema collection.
+ * 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 ExtractRecordType<Schema extends SchemaDeclaration, CollectionName extends keyof Schema> = Schema[CollectionName]['type'];
+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.
@@ -122,12 +69,6 @@ type ExtractRecordType<Schema extends SchemaDeclaration, CollectionName extends
 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".
@@ -162,186 +103,366 @@ type WithExpand<Schema extends SchemaDeclaration, CollectionName extends keyof S
  * Used to unwrap optional relation types.
  *
  * @example
- * NonNullable<Customer | undefined> => Customer
+ * ExcludeUndefined<Customer | undefined> => Customer
  * @internal
  */
-type NonNullable<T> = T extends (infer U) | undefined ? U : T;
+type ExcludeUndefined<T> = T extends (infer U) | undefined ? U : T;
 /**
- * Converts a schema relation type to its corresponding Collection type.
+ * 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>
- * RelationAsCollection<Customer[]> => Collection<Customer>
+ * 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> : Collection<object> : T extends object ? Collection<T> : Collection<object>;
+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 relations - maps field names to their TanStack DB collections.
- * Used to provide pre-configured collections for manual joins.
+ * 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 config: RelationsConfig<Schema, 'jobs'> = {
- *     customer: customersCollection,
- *     address: addressesCollection
- * };
+ * const authorsCollection = createCollection<Schema>(pb, queryClient)('authors');
+ * const booksCollection = createCollection<Schema>(pb, queryClient)('books', {
+ *     expand: {
+ *         author: authorsCollection  // Always expand 'author', upsert into authorsCollection
+ *     }
+ * });
  * ```
  */
-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]>>;
+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 with optional expand and relations.
+ * Options for creating a collection.
  */
-interface CreateCollectionOptions<Schema extends SchemaDeclaration, CollectionName extends keyof Schema, Expand extends string | undefined = undefined> {
+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>>[];
     /**
-     * Pre-configured relation collections for manual TanStack DB joins.
+     * 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
-     * const jobsCollection = factory.create('jobs', {
-     *     relations: {
-     *         customer: customersCollection,
-     *         address: addressesCollection
+     * // 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
+     * });
      * ```
      */
-    relations?: RelationsConfig<Schema, CollectionName>;
+    onInsert?: InsertMutationFn<ExtractRecordType<Schema, CollectionName>> | false;
     /**
-     * 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.
+     * 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
-     * // Single relation
-     * const jobsCollection = factory.create('jobs', {
-     *     expand: 'customer'  // Type inference works automatically
+     * // 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'] });
+     *     }
      * });
      *
-     * // Multiple relations with type inference
-     * const jobsCollection = factory.create('jobs', {
-     *     expand: 'customer,address' as const  // `as const` gives proper typing
+     * // Disable deletes (read-only collection)
+     * const collection = createCollection<Schema>(pb, queryClient)('books', {
+     *     onDelete: false
      * });
      * ```
      */
-    expand?: Expand;
+    onDelete?: DeleteMutationFn<ExtractRecordType<Schema, CollectionName>> | false;
     /**
-     * Whether to automatically sync (fetch) data when the collection is created.
-     * Default: false (lazy - sync starts after first query becomes active).
+     * 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
-     * // 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
+     * // 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'
      * });
      * ```
      */
-    startSync?: boolean;
+    syncMode?: 'eager' | 'on-demand';
 }
 
 /**
- * Map of collection names to TanStack DB Collection instances.
- * Keys are user-defined strings, values are Collection instances.
+ * 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 stores = {
- *     jobs: jobsCollection,
- *     customers: customersCollection,
- *     addresses: addressesCollection
- * };
+ * 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
  * ```
  */
-type CollectionsMap = Record<string, Collection<any>>;
+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>;
+
+/**
+ * UseStore hook type for variadic collection access.
+ * @internal
+ */
+type UseStoreFn<CollectionsMap> = <K extends (keyof CollectionsMap)[]>(...keys: K) => {
+    [I in keyof K]: K[I] extends keyof CollectionsMap ? CollectionsMap[K[I]] : never;
+};
 /**
- * Props for the CollectionsProvider component.
+ * Return type for createReactProvider function.
  */
-interface CollectionsProviderProps {
-    /** Map of collection name to Collection instance */
-    collections: CollectionsMap;
-    /** React children to render */
-    children: ReactNode;
+interface ReactProviderResult<CollectionsMap> {
+    /**
+     * React Context Provider component.
+     * Wrap your app with this provider to make collections available to useStore.
+     */
+    Provider: React.FC<{
+        children: ReactNode;
+    }>;
+    /**
+     * Hook to access collections from the provider.
+     * Uses variadic arguments for clean syntax with automatic type inference.
+     *
+     * @example
+     * ```tsx
+     * // Single collection
+     * const [books] = useStore('books');
+     *
+     * // Multiple collections (no 'as const' needed!)
+     * const [books, authors] = useStore('books', 'authors');
+     * ```
+     */
+    useStore: UseStoreFn<CollectionsMap>;
 }
 /**
- * Provider component that makes collections available to all child components.
- * Wrap your app with this provider to use the useStore and useStores hooks.
+ * Creates a React Provider and useStore hook from a collections map.
+ *
+ * @param collections - Map of collection keys to Collection instances
+ * @returns Object containing Provider component and useStore hook
  *
  * @example
+ * Basic usage:
  * ```tsx
- * const factory = new CollectionFactory<Schema>(pb, queryClient);
+ * import { createCollection, createReactProvider } from 'pbtsdb';
+ * import { useLiveQuery } from '@tanstack/react-db';
+ *
+ * // Step 1: Create collections
+ * const c = createCollection<Schema>(pb, queryClient);
  * const collections = {
- *     jobs: factory.create('jobs'),
- *     customers: factory.create('customers'),
- *     addresses: factory.create('addresses')
+ *     books: c('books', {}),
+ *     authors: c('authors', {}),
  * };
  *
+ * // Step 2: Wrap for React
+ * const { Provider, useStore } = createReactProvider(collections);
+ *
+ * // Step 3: Wrap your app
  * function App() {
  *     return (
- *         <CollectionsProvider collections={collections}>
- *             <YourApp />
- *         </CollectionsProvider>
+ *         <QueryClientProvider client={queryClient}>
+ *             <Provider>
+ *                 <BooksList />
+ *             </Provider>
+ *         </QueryClientProvider>
  *     );
  * }
- * ```
- */
-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>
- *     );
+ * // Step 4: Use in components
+ * function BooksList() {
+ *     const [books] = useStore('books');
+ *     const { data } = useLiveQuery((q) => q.from({ books }));
+ *     return <div>{data?.map(book => <p key={book.id}>{book.title}</p>)}</div>;
  * }
  * ```
- */
-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
+ * Variadic useStore pattern:
  * ```tsx
- * function JobsWithCustomers() {
- *     const [jobsCollection, customersCollection] = useStores<
- *         [JobsRecord, CustomersRecord]
- *     >(['jobs', 'customers']);
+ * function BooksWithAuthors() {
+ *     const [books, authors] = useStore('books', 'authors');
  *
  *     const { data } = useLiveQuery((q) =>
- *         q.from({ job: jobsCollection })
+ *         q.from({ book: books })
  *          .join(
- *              { customer: customersCollection },
- *              ({ job, customer }) => eq(job.customer, customer.id),
+ *              { author: authors },
+ *              ({ book, author }) => eq(book.author, author.id),
  *              'left'
  *          )
  *     );
@@ -349,201 +470,37 @@ declare function useStore<T extends object = object>(key: string): Collection<T>
  *     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)
+ * @example
+ * With auto-expand collections:
+ * ```tsx
+ * const c = createCollection<Schema>(pb, queryClient);
+ * const authors = c('authors', {});
+ * const books = c('books', {
+ *     expand: {
+ *         author: authors
+ *     }
+ * });
+ *
+ * const { Provider, useStore } = createReactProvider({ authors, books });
+ *
+ * function BooksWithExpandedAuthors() {
+ *     const [books] = useStore('books');
+ *     const { data } = useLiveQuery((q) => q.from({ books }));
+ *
+ *     return (
+ *         <ul>
+ *             {data?.map(book => (
+ *                 <li key={book.id}>
+ *                     {book.title} by {book.expand?.author?.name}
+ *                 </li>
+ *             ))}
+ *         </ul>
+ *     );
+ * }
+ * ```
  */
-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;
-}
+declare function createReactProvider<CollectionsMap extends Record<string, any>>(collections: CollectionsMap): ReactProviderResult<CollectionsMap>;
 
 /**
  * Logger interface for subscription events and internal operations.
@@ -556,6 +513,12 @@ interface Logger {
      * @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
@@ -577,19 +540,14 @@ interface Logger {
  *
  * @example
  * ```ts
- * import { setLogger } from 'pocketbase-tanstack-db';
+ * import { setLogger } from 'pbtsdb';
  *
- * // Example: Integration with a custom logging service
+ * // Integration with a custom logging service
  * setLogger({
- *     debug: (msg, context) => {
- *         myLogger.debug(msg, context);
- *     },
- *     warn: (msg, context) => {
- *         myLogger.warn(msg, context);
- *     },
+ *     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 });
  *     },
  * });
@@ -597,7 +555,7 @@ interface Logger {
  *
  * @example
  * ```ts
- * // Example: Disable all logging
+ * // Disable all logging
  * setLogger({
  *     debug: () => {},
  *     warn: () => {},
@@ -611,4 +569,19 @@ declare function setLogger(customLogger: Logger): void;
  */
 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 };
+/**
+ * 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 };