@tanstack/db 0.4.9 → 0.4.11

package/dist/cjs/query/live-query-collection.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"live-query-collection.cjs","sources":["../../../src/query/live-query-collection.ts"],"sourcesContent":["import { createCollection } from \"../collection/index.js\"\nimport { CollectionConfigBuilder } from \"./live/collection-config-builder.js\"\nimport {\n  getBuilderFromConfig,\n  registerCollectionBuilder,\n} from \"./live/collection-registry.js\"\nimport type { LiveQueryCollectionUtils } from \"./live/collection-config-builder.js\"\nimport type { LiveQueryCollectionConfig } from \"./live/types.js\"\nimport type { InitialQueryBuilder, QueryBuilder } from \"./builder/index.js\"\nimport type { Collection } from \"../collection/index.js\"\nimport type {\n  CollectionConfig,\n  CollectionConfigSingleRowOption,\n  NonSingleResult,\n  SingleResult,\n  UtilsRecord,\n} from \"../types.js\"\nimport type { Context, GetResult } from \"./builder/types.js\"\n\ntype CollectionConfigForContext<\n  TContext extends Context,\n  TResult extends object,\n> = TContext extends SingleResult\n  ? CollectionConfigSingleRowOption<TResult> & SingleResult\n  : CollectionConfigSingleRowOption<TResult> & NonSingleResult\n\ntype CollectionForContext<\n  TContext extends Context,\n  TResult extends object,\n> = TContext extends SingleResult\n  ? Collection<TResult> & SingleResult\n  : Collection<TResult> & NonSingleResult\n\n/**\n * Creates live query collection options for use with createCollection\n *\n * @example\n * ```typescript\n * const options = liveQueryCollectionOptions({\n *   // id is optional - will auto-generate if not provided\n *   query: (q) => q\n *     .from({ post: postsCollection })\n *     .where(({ post }) => eq(post.published, true))\n *     .select(({ post }) => ({\n *       id: post.id,\n *       title: post.title,\n *       content: post.content,\n *     })),\n *   // getKey is optional - will use stream key if not provided\n * })\n *\n * const collection = createCollection(options)\n * ```\n *\n * @param config - Configuration options for the live query collection\n * @returns Collection options that can be passed to createCollection\n */\nexport function liveQueryCollectionOptions<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n>(\n  config: LiveQueryCollectionConfig<TContext, TResult>\n): CollectionConfigForContext<TContext, TResult> & {\n  utils: LiveQueryCollectionUtils\n} {\n  const collectionConfigBuilder = new CollectionConfigBuilder<\n    TContext,\n    TResult\n  >(config)\n  return collectionConfigBuilder.getConfig() as CollectionConfigForContext<\n    TContext,\n    TResult\n  > & { utils: LiveQueryCollectionUtils }\n}\n\n/**\n * Creates a live query collection directly\n *\n * @example\n * ```typescript\n * // Minimal usage - just pass a query function\n * const activeUsers = createLiveQueryCollection(\n *   (q) => q\n *     .from({ user: usersCollection })\n *     .where(({ user }) => eq(user.active, true))\n *     .select(({ user }) => ({ id: user.id, name: user.name }))\n * )\n *\n * // Full configuration with custom options\n * const searchResults = createLiveQueryCollection({\n *   id: \"search-results\", // Custom ID (auto-generated if omitted)\n *   query: (q) => q\n *     .from({ post: postsCollection })\n *     .where(({ post }) => like(post.title, `%${searchTerm}%`))\n *     .select(({ post }) => ({\n *       id: post.id,\n *       title: post.title,\n *       excerpt: post.excerpt,\n *     })),\n *   getKey: (item) => item.id, // Custom key function (uses stream key if omitted)\n *   utils: {\n *     updateSearchTerm: (newTerm: string) => {\n *       // Custom utility functions\n *     }\n *   }\n * })\n * ```\n */\n\n// Overload 1: Accept just the query function\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n>(\n  query: (q: InitialQueryBuilder) => QueryBuilder<TContext>\n): CollectionForContext<TContext, TResult> & {\n  utils: LiveQueryCollectionUtils\n}\n\n// Overload 2: Accept full config object with optional utilities\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n  TUtils extends UtilsRecord = {},\n>(\n  config: LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils }\n): CollectionForContext<TContext, TResult> & {\n  utils: LiveQueryCollectionUtils & TUtils\n}\n\n// Implementation\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n  TUtils extends UtilsRecord = {},\n>(\n  configOrQuery:\n    | (LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils })\n    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>)\n): CollectionForContext<TContext, TResult> & {\n  utils: LiveQueryCollectionUtils & TUtils\n} {\n  // Determine if the argument is a function (query) or a config object\n  if (typeof configOrQuery === `function`) {\n    // Simple query function case\n    const config: LiveQueryCollectionConfig<TContext, TResult> = {\n      query: configOrQuery as (\n        q: InitialQueryBuilder\n      ) => QueryBuilder<TContext>,\n    }\n    const options = liveQueryCollectionOptions<TContext, TResult>(config)\n    return bridgeToCreateCollection(options) as CollectionForContext<\n      TContext,\n      TResult\n    > & { utils: LiveQueryCollectionUtils & TUtils }\n  } else {\n    // Config object case\n    const config = configOrQuery as LiveQueryCollectionConfig<\n      TContext,\n      TResult\n    > & { utils?: TUtils }\n    const options = liveQueryCollectionOptions<TContext, TResult>(config)\n\n    // Merge custom utils if provided, preserving the getBuilder() method for dependency tracking\n    if (config.utils) {\n      options.utils = { ...options.utils, ...config.utils }\n    }\n\n    return bridgeToCreateCollection(options) as CollectionForContext<\n      TContext,\n      TResult\n    > & { utils: LiveQueryCollectionUtils & TUtils }\n  }\n}\n\n/**\n * Bridge function that handles the type compatibility between query2's TResult\n * and core collection's output type without exposing ugly type assertions to users\n */\nfunction bridgeToCreateCollection<\n  TResult extends object,\n  TUtils extends UtilsRecord = {},\n>(\n  options: CollectionConfig<TResult> & { utils: TUtils }\n): Collection<TResult, string | number, TUtils> {\n  const collection = createCollection(options as any) as unknown as Collection<\n    TResult,\n    string | number,\n    LiveQueryCollectionUtils\n  >\n\n  const builder = getBuilderFromConfig(options)\n  if (builder) {\n    registerCollectionBuilder(collection, builder)\n  }\n\n  return collection as unknown as Collection<TResult, string | number, TUtils>\n}\n"],"names":["collectionConfigBuilder","CollectionConfigBuilder","createCollection","getBuilderFromConfig","registerCollectionBuilder"],"mappings":";;;;;AAyDO,SAAS,2BAId,QAGA;AACA,QAAMA,4BAA0B,IAAIC,wBAAAA,wBAGlC,MAAM;AACR,SAAOD,0BAAwB,UAAA;AAIjC;AA0DO,SAAS,0BAKd,eAKA;AAEA,MAAI,OAAO,kBAAkB,YAAY;AAEvC,UAAM,SAAuD;AAAA,MAC3D,OAAO;AAAA,IAAA;AAIT,UAAM,UAAU,2BAA8C,MAAM;AACpE,WAAO,yBAAyB,OAAO;AAAA,EAIzC,OAAO;AAEL,UAAM,SAAS;AAIf,UAAM,UAAU,2BAA8C,MAAM;AAGpE,QAAI,OAAO,OAAO;AAChB,cAAQ,QAAQ,EAAE,GAAG,QAAQ,OAAO,GAAG,OAAO,MAAA;AAAA,IAChD;AAEA,WAAO,yBAAyB,OAAO;AAAA,EAIzC;AACF;AAMA,SAAS,yBAIP,SAC8C;AAC9C,QAAM,aAAaE,MAAAA,iBAAiB,OAAc;AAMlD,QAAM,UAAUC,mBAAAA,qBAAqB,OAAO;AAC5C,MAAI,SAAS;AACXC,uBAAAA,0BAA0B,YAAY,OAAO;AAAA,EAC/C;AAEA,SAAO;AACT;;;"}
+{"version":3,"file":"live-query-collection.cjs","sources":["../../../src/query/live-query-collection.ts"],"sourcesContent":["import { createCollection } from \"../collection/index.js\"\nimport { CollectionConfigBuilder } from \"./live/collection-config-builder.js\"\nimport {\n  getBuilderFromConfig,\n  registerCollectionBuilder,\n} from \"./live/collection-registry.js\"\nimport type { LiveQueryCollectionUtils } from \"./live/collection-config-builder.js\"\nimport type { LiveQueryCollectionConfig } from \"./live/types.js\"\nimport type { InitialQueryBuilder, QueryBuilder } from \"./builder/index.js\"\nimport type { Collection } from \"../collection/index.js\"\nimport type {\n  CollectionConfig,\n  CollectionConfigSingleRowOption,\n  NonSingleResult,\n  SingleResult,\n  UtilsRecord,\n} from \"../types.js\"\nimport type { Context, GetResult } from \"./builder/types.js\"\n\ntype CollectionConfigForContext<\n  TContext extends Context,\n  TResult extends object,\n  TUtils extends UtilsRecord = {},\n> = TContext extends SingleResult\n  ? CollectionConfigSingleRowOption<TResult, string | number, never, TUtils> &\n      SingleResult\n  : CollectionConfigSingleRowOption<TResult, string | number, never, TUtils> &\n      NonSingleResult\n\ntype CollectionForContext<\n  TContext extends Context,\n  TResult extends object,\n  TUtils extends UtilsRecord = {},\n> = TContext extends SingleResult\n  ? Collection<TResult, string | number, TUtils> & SingleResult\n  : Collection<TResult, string | number, TUtils> & NonSingleResult\n\n/**\n * Creates live query collection options for use with createCollection\n *\n * @example\n * ```typescript\n * const options = liveQueryCollectionOptions({\n *   // id is optional - will auto-generate if not provided\n *   query: (q) => q\n *     .from({ post: postsCollection })\n *     .where(({ post }) => eq(post.published, true))\n *     .select(({ post }) => ({\n *       id: post.id,\n *       title: post.title,\n *       content: post.content,\n *     })),\n *   // getKey is optional - will use stream key if not provided\n * })\n *\n * const collection = createCollection(options)\n * ```\n *\n * @param config - Configuration options for the live query collection\n * @returns Collection options that can be passed to createCollection\n */\nexport function liveQueryCollectionOptions<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n>(\n  config: LiveQueryCollectionConfig<TContext, TResult>\n): CollectionConfigForContext<TContext, TResult> & {\n  utils: LiveQueryCollectionUtils\n} {\n  const collectionConfigBuilder = new CollectionConfigBuilder<\n    TContext,\n    TResult\n  >(config)\n  return collectionConfigBuilder.getConfig() as CollectionConfigForContext<\n    TContext,\n    TResult\n  > & { utils: LiveQueryCollectionUtils }\n}\n\n/**\n * Creates a live query collection directly\n *\n * @example\n * ```typescript\n * // Minimal usage - just pass a query function\n * const activeUsers = createLiveQueryCollection(\n *   (q) => q\n *     .from({ user: usersCollection })\n *     .where(({ user }) => eq(user.active, true))\n *     .select(({ user }) => ({ id: user.id, name: user.name }))\n * )\n *\n * // Full configuration with custom options\n * const searchResults = createLiveQueryCollection({\n *   id: \"search-results\", // Custom ID (auto-generated if omitted)\n *   query: (q) => q\n *     .from({ post: postsCollection })\n *     .where(({ post }) => like(post.title, `%${searchTerm}%`))\n *     .select(({ post }) => ({\n *       id: post.id,\n *       title: post.title,\n *       excerpt: post.excerpt,\n *     })),\n *   getKey: (item) => item.id, // Custom key function (uses stream key if omitted)\n *   utils: {\n *     updateSearchTerm: (newTerm: string) => {\n *       // Custom utility functions\n *     }\n *   }\n * })\n * ```\n */\n\n// Overload 1: Accept just the query function\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n>(\n  query: (q: InitialQueryBuilder) => QueryBuilder<TContext>\n): CollectionForContext<TContext, TResult> & {\n  utils: LiveQueryCollectionUtils\n}\n\n// Overload 2: Accept full config object with optional utilities\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n  TUtils extends UtilsRecord = {},\n>(\n  config: LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils }\n): CollectionForContext<TContext, TResult> & {\n  utils: LiveQueryCollectionUtils & TUtils\n}\n\n// Implementation\nexport function createLiveQueryCollection<\n  TContext extends Context,\n  TResult extends object = GetResult<TContext>,\n  TUtils extends UtilsRecord = {},\n>(\n  configOrQuery:\n    | (LiveQueryCollectionConfig<TContext, TResult> & { utils?: TUtils })\n    | ((q: InitialQueryBuilder) => QueryBuilder<TContext>)\n): CollectionForContext<TContext, TResult> & {\n  utils: LiveQueryCollectionUtils & TUtils\n} {\n  // Determine if the argument is a function (query) or a config object\n  if (typeof configOrQuery === `function`) {\n    // Simple query function case\n    const config: LiveQueryCollectionConfig<TContext, TResult> = {\n      query: configOrQuery as (\n        q: InitialQueryBuilder\n      ) => QueryBuilder<TContext>,\n    }\n    const options = liveQueryCollectionOptions<TContext, TResult>(config)\n    return bridgeToCreateCollection(options) as CollectionForContext<\n      TContext,\n      TResult\n    > & { utils: LiveQueryCollectionUtils & TUtils }\n  } else {\n    // Config object case\n    const config = configOrQuery as LiveQueryCollectionConfig<\n      TContext,\n      TResult\n    > & { utils?: TUtils }\n    const options = liveQueryCollectionOptions<TContext, TResult>(config)\n\n    // Merge custom utils if provided, preserving the getBuilder() method for dependency tracking\n    if (config.utils) {\n      options.utils = { ...options.utils, ...config.utils }\n    }\n\n    return bridgeToCreateCollection(options) as CollectionForContext<\n      TContext,\n      TResult\n    > & { utils: LiveQueryCollectionUtils & TUtils }\n  }\n}\n\n/**\n * Bridge function that handles the type compatibility between query2's TResult\n * and core collection's output type without exposing ugly type assertions to users\n */\nfunction bridgeToCreateCollection<\n  TResult extends object,\n  TUtils extends UtilsRecord = {},\n>(\n  options: CollectionConfig<TResult> & { utils: TUtils }\n): Collection<TResult, string | number, TUtils> {\n  const collection = createCollection(options as any) as unknown as Collection<\n    TResult,\n    string | number,\n    LiveQueryCollectionUtils\n  >\n\n  const builder = getBuilderFromConfig(options)\n  if (builder) {\n    registerCollectionBuilder(collection, builder)\n  }\n\n  return collection as unknown as Collection<TResult, string | number, TUtils>\n}\n"],"names":["collectionConfigBuilder","CollectionConfigBuilder","createCollection","getBuilderFromConfig","registerCollectionBuilder"],"mappings":";;;;;AA6DO,SAAS,2BAId,QAGA;AACA,QAAMA,4BAA0B,IAAIC,wBAAAA,wBAGlC,MAAM;AACR,SAAOD,0BAAwB,UAAA;AAIjC;AA0DO,SAAS,0BAKd,eAKA;AAEA,MAAI,OAAO,kBAAkB,YAAY;AAEvC,UAAM,SAAuD;AAAA,MAC3D,OAAO;AAAA,IAAA;AAIT,UAAM,UAAU,2BAA8C,MAAM;AACpE,WAAO,yBAAyB,OAAO;AAAA,EAIzC,OAAO;AAEL,UAAM,SAAS;AAIf,UAAM,UAAU,2BAA8C,MAAM;AAGpE,QAAI,OAAO,OAAO;AAChB,cAAQ,QAAQ,EAAE,GAAG,QAAQ,OAAO,GAAG,OAAO,MAAA;AAAA,IAChD;AAEA,WAAO,yBAAyB,OAAO;AAAA,EAIzC;AACF;AAMA,SAAS,yBAIP,SAC8C;AAC9C,QAAM,aAAaE,MAAAA,iBAAiB,OAAc;AAMlD,QAAM,UAAUC,mBAAAA,qBAAqB,OAAO;AAC5C,MAAI,SAAS;AACXC,uBAAAA,0BAA0B,YAAY,OAAO;AAAA,EAC/C;AAEA,SAAO;AACT;;;"}

package/dist/cjs/query/live-query-collection.d.cts

@@ -4,8 +4,8 @@ import { InitialQueryBuilder, QueryBuilder } from './builder/index.js';
 import { Collection } from '../collection/index.js';
 import { CollectionConfigSingleRowOption, NonSingleResult, SingleResult, UtilsRecord } from '../types.js';
 import { Context, GetResult } from './builder/types.js';
-type CollectionConfigForContext<TContext extends Context, TResult extends object> = TContext extends SingleResult ? CollectionConfigSingleRowOption<TResult> & SingleResult : CollectionConfigSingleRowOption<TResult> & NonSingleResult;
-type CollectionForContext<TContext extends Context, TResult extends object> = TContext extends SingleResult ? Collection<TResult> & SingleResult : Collection<TResult> & NonSingleResult;
+type CollectionConfigForContext<TContext extends Context, TResult extends object, TUtils extends UtilsRecord = {}> = TContext extends SingleResult ? CollectionConfigSingleRowOption<TResult, string | number, never, TUtils> & SingleResult : CollectionConfigSingleRowOption<TResult, string | number, never, TUtils> & NonSingleResult;
+type CollectionForContext<TContext extends Context, TResult extends object, TUtils extends UtilsRecord = {}> = TContext extends SingleResult ? Collection<TResult, string | number, TUtils> & SingleResult : Collection<TResult, string | number, TUtils> & NonSingleResult;
 /**
  * Creates live query collection options for use with createCollection
  *

package/dist/cjs/types.d.cts

@@ -3,6 +3,7 @@ import { Collection } from './collection/index.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { Transaction } from './transactions.cjs';
 import { BasicExpression, OrderBy } from './query/ir.js';
+import { EventEmitter } from './event-emitter.js';
 /**
  * Helper type to extract the output type from a standard schema
  *
@@ -92,15 +93,74 @@ type Value<TExtensions = never> = string | number | boolean | bigint | null | TE
 };
 export type Row<TExtensions = never> = Record<string, Value<TExtensions>>;
 export type OperationType = `insert` | `update` | `delete`;
-export type OnLoadMoreOptions = {
+/**
+ * Subscription status values
+ */
+export type SubscriptionStatus = `ready` | `loadingSubset`;
+/**
+ * Event emitted when subscription status changes
+ */
+export interface SubscriptionStatusChangeEvent {
+    type: `status:change`;
+    subscription: Subscription;
+    previousStatus: SubscriptionStatus;
+    status: SubscriptionStatus;
+}
+/**
+ * Event emitted when subscription status changes to a specific status
+ */
+export interface SubscriptionStatusEvent<T extends SubscriptionStatus> {
+    type: `status:${T}`;
+    subscription: Subscription;
+    previousStatus: SubscriptionStatus;
+    status: T;
+}
+/**
+ * Event emitted when subscription is unsubscribed
+ */
+export interface SubscriptionUnsubscribedEvent {
+    type: `unsubscribed`;
+    subscription: Subscription;
+}
+/**
+ * All subscription events
+ */
+export type SubscriptionEvents = {
+    "status:change": SubscriptionStatusChangeEvent;
+    "status:ready": SubscriptionStatusEvent<`ready`>;
+    "status:loadingSubset": SubscriptionStatusEvent<`loadingSubset`>;
+    unsubscribed: SubscriptionUnsubscribedEvent;
+};
+/**
+ * Public interface for a collection subscription
+ * Used by sync implementations to track subscription lifecycle
+ */
+export interface Subscription extends EventEmitter<SubscriptionEvents> {
+    /** Current status of the subscription */
+    readonly status: SubscriptionStatus;
+}
+export type LoadSubsetOptions = {
+    /** The where expression to filter the data */
     where?: BasicExpression<boolean>;
+    /** The order by clause to sort the data */
     orderBy?: OrderBy;
+    /** The limit of the data to load */
     limit?: number;
+    /**
+     * The subscription that triggered the load.
+     * Advanced sync implementations can use this for:
+     * - LRU caching keyed by subscription
+     * - Reference counting to track active subscriptions
+     * - Subscribing to subscription events (e.g., finalization/unsubscribe)
+     * @optional Available when called from CollectionSubscription, may be undefined for direct calls
+     */
+    subscription?: Subscription;
 };
+export type LoadSubsetFn = (options: LoadSubsetOptions) => true | Promise<void>;
 export type CleanupFn = () => void;
 export type SyncConfigRes = {
     cleanup?: CleanupFn;
-    onLoadMore?: (options: OnLoadMoreOptions) => void | Promise<void>;
+    loadSubset?: LoadSubsetFn;
 };
 export interface SyncConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number> {
     sync: (params: {
@@ -161,21 +221,21 @@ export interface InsertConfig {
     /** Whether to apply optimistic updates immediately. Defaults to true. */
     optimistic?: boolean;
 }
-export type UpdateMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>> = {
+export type UpdateMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord> = {
     transaction: TransactionWithMutations<T, `update`>;
     collection: Collection<T, TKey, TUtils>;
 };
-export type InsertMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>> = {
+export type InsertMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord> = {
     transaction: TransactionWithMutations<T, `insert`>;
     collection: Collection<T, TKey, TUtils>;
 };
-export type DeleteMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>> = {
+export type DeleteMutationFnParams<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord> = {
     transaction: TransactionWithMutations<T, `delete`>;
     collection: Collection<T, TKey, TUtils>;
 };
-export type InsertMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>, TReturn = any> = (params: InsertMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>;
-export type UpdateMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>, TReturn = any> = (params: UpdateMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>;
-export type DeleteMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = Record<string, Fn>, TReturn = any> = (params: DeleteMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>;
+export type InsertMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord, TReturn = any> = (params: InsertMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>;
+export type UpdateMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord, TReturn = any> = (params: UpdateMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>;
+export type DeleteMutationFn<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord, TReturn = any> = (params: DeleteMutationFnParams<T, TKey, TUtils>) => Promise<TReturn>;
 /**
  * Collection status values for lifecycle management
  * @example
@@ -202,7 +262,8 @@ export type CollectionStatus =
  | `error`
 /** Collection has been cleaned up and resources freed */
  | `cleaned-up`;
-export interface BaseCollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = Record<string, Fn>, TReturn = any> {
+export type SyncMode = `eager` | `on-demand`;
+export interface BaseCollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = UtilsRecord, TReturn = any> {
     id?: string;
     schema?: TSchema;
     /**
@@ -251,6 +312,15 @@ export interface BaseCollectionConfig<T extends object = Record<string, unknown>
      * compare: (x, y) => x.createdAt.getTime() - y.createdAt.getTime()
      */
     compare?: (x: T, y: T) => number;
+    /**
+     * The mode of sync to use for the collection.
+     * @default `eager`
+     * @description
+     * - `eager`: syncs all data immediately on preload
+     * - `on-demand`: syncs data in incremental snapshots when the collection is queried
+     * The exact implementation of the sync mode is up to the sync implementation.
+     */
+    syncMode?: SyncMode;
     /**
      * Optional asynchronous handler function called before an insert operation
      * @param params Object containing transaction and collection information
@@ -379,8 +449,9 @@ export interface BaseCollectionConfig<T extends object = Record<string, unknown>
      * }
      */
     onDelete?: DeleteMutationFn<T, TKey, TUtils, TReturn>;
+    utils?: TUtils;
 }
-export interface CollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = never> extends BaseCollectionConfig<T, TKey, TSchema> {
+export interface CollectionConfig<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = UtilsRecord> extends BaseCollectionConfig<T, TKey, TSchema, TUtils> {
     sync: SyncConfig<T, TKey>;
 }
 export type SingleResult = {
@@ -395,7 +466,7 @@ export type MaybeSingleResult = {
      */
     singleResult?: true;
 };
-export type CollectionConfigSingleRowOption<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = never> = CollectionConfig<T, TKey, TSchema> & MaybeSingleResult;
+export type CollectionConfigSingleRowOption<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TSchema extends StandardSchemaV1 = never, TUtils extends UtilsRecord = {}> = CollectionConfig<T, TKey, TSchema, TUtils> & MaybeSingleResult;
 export type ChangesPayload<T extends object = Record<string, unknown>> = Array<ChangeMessage<T>>;
 /**
  * An input row from a collection

package/dist/esm/collection/events.d.ts

@@ -1,3 +1,4 @@
+import { EventEmitter } from '../event-emitter.js';
 import { Collection } from './index.js';
 import { CollectionStatus } from '../types.js';
 /**
@@ -27,25 +28,35 @@ export interface CollectionSubscribersChangeEvent {
     previousSubscriberCount: number;
     subscriberCount: number;
 }
+/**
+ * Event emitted when the collection's loading more state changes
+ */
+export interface CollectionLoadingSubsetChangeEvent {
+    type: `loadingSubset:change`;
+    collection: Collection<any, any, any, any, any>;
+    isLoadingSubset: boolean;
+    previousIsLoadingSubset: boolean;
+    loadingSubsetTransition: `start` | `end`;
+}
 export type AllCollectionEvents = {
     "status:change": CollectionStatusChangeEvent;
     "subscribers:change": CollectionSubscribersChangeEvent;
+    "loadingSubset:change": CollectionLoadingSubsetChangeEvent;
 } & {
     [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>;
 };
-export type CollectionEvent = AllCollectionEvents[keyof AllCollectionEvents] | CollectionStatusChangeEvent | CollectionSubscribersChangeEvent;
+export type CollectionEvent = AllCollectionEvents[keyof AllCollectionEvents] | CollectionStatusChangeEvent | CollectionSubscribersChangeEvent | CollectionLoadingSubsetChangeEvent;
 export type CollectionEventHandler<T extends keyof AllCollectionEvents> = (event: AllCollectionEvents[T]) => void;
-export declare class CollectionEventsManager {
+export declare class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {
     private collection;
-    private listeners;
     constructor();
     setDeps(deps: {
         collection: Collection<any, any, any, any, any>;
     }): void;
-    on<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): () => void;
-    once<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): () => void;
-    off<T extends keyof AllCollectionEvents>(event: T, callback: CollectionEventHandler<T>): void;
-    waitFor<T extends keyof AllCollectionEvents>(event: T, timeout?: number): Promise<AllCollectionEvents[T]>;
+    /**
+     * Emit an event to all listeners
+     * Public API for emitting collection events
+     */
     emit<T extends keyof AllCollectionEvents>(event: T, eventPayload: AllCollectionEvents[T]): void;
     emitStatusChange<T extends CollectionStatus>(status: T, previousStatus: CollectionStatus): void;
     emitSubscribersChange(subscriberCount: number, previousSubscriberCount: number): void;

package/dist/esm/collection/events.js

@@ -1,59 +1,17 @@
-class CollectionEventsManager {
+import { EventEmitter } from "../event-emitter.js";
+class CollectionEventsManager extends EventEmitter {
   constructor() {
-    this.listeners = /* @__PURE__ */ new Map();
+    super();
   }
   setDeps(deps) {
     this.collection = deps.collection;
   }
-  on(event, callback) {
-    if (!this.listeners.has(event)) {
-      this.listeners.set(event, /* @__PURE__ */ new Set());
-    }
-    this.listeners.get(event).add(callback);
-    return () => {
-      this.listeners.get(event)?.delete(callback);
-    };
-  }
-  once(event, callback) {
-    const unsubscribe = this.on(event, (eventPayload) => {
-      callback(eventPayload);
-      unsubscribe();
-    });
-    return unsubscribe;
-  }
-  off(event, callback) {
-    this.listeners.get(event)?.delete(callback);
-  }
-  waitFor(event, timeout) {
-    return new Promise((resolve, reject) => {
-      let timeoutId;
-      const unsubscribe = this.on(event, (eventPayload) => {
-        if (timeoutId) {
-          clearTimeout(timeoutId);
-          timeoutId = void 0;
-        }
-        resolve(eventPayload);
-        unsubscribe();
-      });
-      if (timeout) {
-        timeoutId = setTimeout(() => {
-          timeoutId = void 0;
-          unsubscribe();
-          reject(new Error(`Timeout waiting for event ${event}`));
-        }, timeout);
-      }
-    });
-  }
+  /**
+   * Emit an event to all listeners
+   * Public API for emitting collection events
+   */
   emit(event, eventPayload) {
-    this.listeners.get(event)?.forEach((listener) => {
-      try {
-        listener(eventPayload);
-      } catch (error) {
-        queueMicrotask(() => {
-          throw error;
-        });
-      }
-    });
+    this.emitInner(event, eventPayload);
   }
   emitStatusChange(status, previousStatus) {
     this.emit(`status:change`, {
@@ -79,7 +37,7 @@ class CollectionEventsManager {
     });
   }
   cleanup() {
-    this.listeners.clear();
+    this.clearListeners();
   }
 }
 export {

package/dist/esm/collection/events.js.map

@@ -1 +1 @@
-{"version":3,"file":"events.js","sources":["../../../src/collection/events.ts"],"sourcesContent":["import type { Collection } from \"./index.js\"\nimport type { CollectionStatus } from \"../types.js\"\n\n/**\n * Event emitted when the collection status changes\n */\nexport interface CollectionStatusChangeEvent {\n  type: `status:change`\n  collection: Collection\n  previousStatus: CollectionStatus\n  status: CollectionStatus\n}\n\n/**\n * Event emitted when the collection status changes to a specific status\n */\nexport interface CollectionStatusEvent<T extends CollectionStatus> {\n  type: `status:${T}`\n  collection: Collection\n  previousStatus: CollectionStatus\n  status: T\n}\n\n/**\n * Event emitted when the number of subscribers to the collection changes\n */\nexport interface CollectionSubscribersChangeEvent {\n  type: `subscribers:change`\n  collection: Collection\n  previousSubscriberCount: number\n  subscriberCount: number\n}\n\nexport type AllCollectionEvents = {\n  \"status:change\": CollectionStatusChangeEvent\n  \"subscribers:change\": CollectionSubscribersChangeEvent\n} & {\n  [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>\n}\n\nexport type CollectionEvent =\n  | AllCollectionEvents[keyof AllCollectionEvents]\n  | CollectionStatusChangeEvent\n  | CollectionSubscribersChangeEvent\n\nexport type CollectionEventHandler<T extends keyof AllCollectionEvents> = (\n  event: AllCollectionEvents[T]\n) => void\n\nexport class CollectionEventsManager {\n  private collection!: Collection<any, any, any, any, any>\n  private listeners = new Map<\n    keyof AllCollectionEvents,\n    Set<CollectionEventHandler<any>>\n  >()\n\n  constructor() {}\n\n  setDeps(deps: { collection: Collection<any, any, any, any, any> }) {\n    this.collection = deps.collection\n  }\n\n  on<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    if (!this.listeners.has(event)) {\n      this.listeners.set(event, new Set())\n    }\n    this.listeners.get(event)!.add(callback)\n\n    return () => {\n      this.listeners.get(event)?.delete(callback)\n    }\n  }\n\n  once<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    const unsubscribe = this.on(event, (eventPayload) => {\n      callback(eventPayload)\n      unsubscribe()\n    })\n    return unsubscribe\n  }\n\n  off<T extends keyof AllCollectionEvents>(\n    event: T,\n    callback: CollectionEventHandler<T>\n  ) {\n    this.listeners.get(event)?.delete(callback)\n  }\n\n  waitFor<T extends keyof AllCollectionEvents>(\n    event: T,\n    timeout?: number\n  ): Promise<AllCollectionEvents[T]> {\n    return new Promise((resolve, reject) => {\n      let timeoutId: NodeJS.Timeout | undefined\n      const unsubscribe = this.on(event, (eventPayload) => {\n        if (timeoutId) {\n          clearTimeout(timeoutId)\n          timeoutId = undefined\n        }\n        resolve(eventPayload)\n        unsubscribe()\n      })\n      if (timeout) {\n        timeoutId = setTimeout(() => {\n          timeoutId = undefined\n          unsubscribe()\n          reject(new Error(`Timeout waiting for event ${event}`))\n        }, timeout)\n      }\n    })\n  }\n\n  emit<T extends keyof AllCollectionEvents>(\n    event: T,\n    eventPayload: AllCollectionEvents[T]\n  ) {\n    this.listeners.get(event)?.forEach((listener) => {\n      try {\n        listener(eventPayload)\n      } catch (error) {\n        // Re-throw in a microtask to surface the error\n        queueMicrotask(() => {\n          throw error\n        })\n      }\n    })\n  }\n\n  emitStatusChange<T extends CollectionStatus>(\n    status: T,\n    previousStatus: CollectionStatus\n  ) {\n    this.emit(`status:change`, {\n      type: `status:change`,\n      collection: this.collection,\n      previousStatus,\n      status,\n    })\n\n    // Emit specific status event using type assertion\n    const eventKey: `status:${T}` = `status:${status}`\n    this.emit(eventKey, {\n      type: eventKey,\n      collection: this.collection,\n      previousStatus,\n      status,\n    } as AllCollectionEvents[`status:${T}`])\n  }\n\n  emitSubscribersChange(\n    subscriberCount: number,\n    previousSubscriberCount: number\n  ) {\n    this.emit(`subscribers:change`, {\n      type: `subscribers:change`,\n      collection: this.collection,\n      previousSubscriberCount,\n      subscriberCount,\n    })\n  }\n\n  cleanup() {\n    this.listeners.clear()\n  }\n}\n"],"names":[],"mappings":"AAiDO,MAAM,wBAAwB;AAAA,EAOnC,cAAc;AALd,SAAQ,gCAAgB,IAAA;AAAA,EAKT;AAAA,EAEf,QAAQ,MAA2D;AACjE,SAAK,aAAa,KAAK;AAAA,EACzB;AAAA,EAEA,GACE,OACA,UACA;AACA,QAAI,CAAC,KAAK,UAAU,IAAI,KAAK,GAAG;AAC9B,WAAK,UAAU,IAAI,OAAO,oBAAI,KAAK;AAAA,IACrC;AACA,SAAK,UAAU,IAAI,KAAK,EAAG,IAAI,QAAQ;AAEvC,WAAO,MAAM;AACX,WAAK,UAAU,IAAI,KAAK,GAAG,OAAO,QAAQ;AAAA,IAC5C;AAAA,EACF;AAAA,EAEA,KACE,OACA,UACA;AACA,UAAM,cAAc,KAAK,GAAG,OAAO,CAAC,iBAAiB;AACnD,eAAS,YAAY;AACrB,kBAAA;AAAA,IACF,CAAC;AACD,WAAO;AAAA,EACT;AAAA,EAEA,IACE,OACA,UACA;AACA,SAAK,UAAU,IAAI,KAAK,GAAG,OAAO,QAAQ;AAAA,EAC5C;AAAA,EAEA,QACE,OACA,SACiC;AACjC,WAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,UAAI;AACJ,YAAM,cAAc,KAAK,GAAG,OAAO,CAAC,iBAAiB;AACnD,YAAI,WAAW;AACb,uBAAa,SAAS;AACtB,sBAAY;AAAA,QACd;AACA,gBAAQ,YAAY;AACpB,oBAAA;AAAA,MACF,CAAC;AACD,UAAI,SAAS;AACX,oBAAY,WAAW,MAAM;AAC3B,sBAAY;AACZ,sBAAA;AACA,iBAAO,IAAI,MAAM,6BAA6B,KAAK,EAAE,CAAC;AAAA,QACxD,GAAG,OAAO;AAAA,MACZ;AAAA,IACF,CAAC;AAAA,EACH;AAAA,EAEA,KACE,OACA,cACA;AACA,SAAK,UAAU,IAAI,KAAK,GAAG,QAAQ,CAAC,aAAa;AAC/C,UAAI;AACF,iBAAS,YAAY;AAAA,MACvB,SAAS,OAAO;AAEd,uBAAe,MAAM;AACnB,gBAAM;AAAA,QACR,CAAC;AAAA,MACH;AAAA,IACF,CAAC;AAAA,EACH;AAAA,EAEA,iBACE,QACA,gBACA;AACA,SAAK,KAAK,iBAAiB;AAAA,MACzB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AAGD,UAAM,WAA0B,UAAU,MAAM;AAChD,SAAK,KAAK,UAAU;AAAA,MAClB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACqC;AAAA,EACzC;AAAA,EAEA,sBACE,iBACA,yBACA;AACA,SAAK,KAAK,sBAAsB;AAAA,MAC9B,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AAAA,EACH;AAAA,EAEA,UAAU;AACR,SAAK,UAAU,MAAA;AAAA,EACjB;AACF;"}
+{"version":3,"file":"events.js","sources":["../../../src/collection/events.ts"],"sourcesContent":["import { EventEmitter } from \"../event-emitter.js\"\nimport type { Collection } from \"./index.js\"\nimport type { CollectionStatus } from \"../types.js\"\n\n/**\n * Event emitted when the collection status changes\n */\nexport interface CollectionStatusChangeEvent {\n  type: `status:change`\n  collection: Collection\n  previousStatus: CollectionStatus\n  status: CollectionStatus\n}\n\n/**\n * Event emitted when the collection status changes to a specific status\n */\nexport interface CollectionStatusEvent<T extends CollectionStatus> {\n  type: `status:${T}`\n  collection: Collection\n  previousStatus: CollectionStatus\n  status: T\n}\n\n/**\n * Event emitted when the number of subscribers to the collection changes\n */\nexport interface CollectionSubscribersChangeEvent {\n  type: `subscribers:change`\n  collection: Collection\n  previousSubscriberCount: number\n  subscriberCount: number\n}\n\n/**\n * Event emitted when the collection's loading more state changes\n */\nexport interface CollectionLoadingSubsetChangeEvent {\n  type: `loadingSubset:change`\n  collection: Collection<any, any, any, any, any>\n  isLoadingSubset: boolean\n  previousIsLoadingSubset: boolean\n  loadingSubsetTransition: `start` | `end`\n}\n\nexport type AllCollectionEvents = {\n  \"status:change\": CollectionStatusChangeEvent\n  \"subscribers:change\": CollectionSubscribersChangeEvent\n  \"loadingSubset:change\": CollectionLoadingSubsetChangeEvent\n} & {\n  [K in CollectionStatus as `status:${K}`]: CollectionStatusEvent<K>\n}\n\nexport type CollectionEvent =\n  | AllCollectionEvents[keyof AllCollectionEvents]\n  | CollectionStatusChangeEvent\n  | CollectionSubscribersChangeEvent\n  | CollectionLoadingSubsetChangeEvent\n\nexport type CollectionEventHandler<T extends keyof AllCollectionEvents> = (\n  event: AllCollectionEvents[T]\n) => void\n\nexport class CollectionEventsManager extends EventEmitter<AllCollectionEvents> {\n  private collection!: Collection<any, any, any, any, any>\n\n  constructor() {\n    super()\n  }\n\n  setDeps(deps: { collection: Collection<any, any, any, any, any> }) {\n    this.collection = deps.collection\n  }\n\n  /**\n   * Emit an event to all listeners\n   * Public API for emitting collection events\n   */\n  emit<T extends keyof AllCollectionEvents>(\n    event: T,\n    eventPayload: AllCollectionEvents[T]\n  ): void {\n    this.emitInner(event, eventPayload)\n  }\n\n  emitStatusChange<T extends CollectionStatus>(\n    status: T,\n    previousStatus: CollectionStatus\n  ) {\n    this.emit(`status:change`, {\n      type: `status:change`,\n      collection: this.collection,\n      previousStatus,\n      status,\n    })\n\n    // Emit specific status event using type assertion\n    const eventKey: `status:${T}` = `status:${status}`\n    this.emit(eventKey, {\n      type: eventKey,\n      collection: this.collection,\n      previousStatus,\n      status,\n    } as AllCollectionEvents[`status:${T}`])\n  }\n\n  emitSubscribersChange(\n    subscriberCount: number,\n    previousSubscriberCount: number\n  ) {\n    this.emit(`subscribers:change`, {\n      type: `subscribers:change`,\n      collection: this.collection,\n      previousSubscriberCount,\n      subscriberCount,\n    })\n  }\n\n  cleanup() {\n    this.clearListeners()\n  }\n}\n"],"names":[],"mappings":";AA+DO,MAAM,gCAAgC,aAAkC;AAAA,EAG7E,cAAc;AACZ,UAAA;AAAA,EACF;AAAA,EAEA,QAAQ,MAA2D;AACjE,SAAK,aAAa,KAAK;AAAA,EACzB;AAAA;AAAA;AAAA;AAAA;AAAA,EAMA,KACE,OACA,cACM;AACN,SAAK,UAAU,OAAO,YAAY;AAAA,EACpC;AAAA,EAEA,iBACE,QACA,gBACA;AACA,SAAK,KAAK,iBAAiB;AAAA,MACzB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AAGD,UAAM,WAA0B,UAAU,MAAM;AAChD,SAAK,KAAK,UAAU;AAAA,MAClB,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACqC;AAAA,EACzC;AAAA,EAEA,sBACE,iBACA,yBACA;AACA,SAAK,KAAK,sBAAsB;AAAA,MAC9B,MAAM;AAAA,MACN,YAAY,KAAK;AAAA,MACjB;AAAA,MACA;AAAA,IAAA,CACD;AAAA,EACH;AAAA,EAEA,UAAU;AACR,SAAK,eAAA;AAAA,EACP;AACF;"}

package/dist/esm/collection/index.d.ts

@@ -1,10 +1,11 @@
 import { CollectionStateManager } from './state.js';
 import { CollectionLifecycleManager } from './lifecycle.js';
+import { CollectionSyncManager } from './sync.js';
 import { CollectionSubscription } from './subscription.js';
 import { AllCollectionEvents, CollectionEventHandler } from './events.js';
 import { BaseIndex, IndexResolver } from '../indexes/base-index.js';
 import { IndexOptions } from '../indexes/index-options.js';
-import { ChangeMessage, CollectionConfig, CollectionStatus, CurrentStateAsChangesOptions, Fn, InferSchemaInput, InferSchemaOutput, InsertConfig, NonSingleResult, OnLoadMoreOptions, OperationConfig, SingleResult, SubscribeChangesOptions, Transaction as TransactionType, UtilsRecord, WritableDeep } from '../types.js';
+import { ChangeMessage, CollectionConfig, CollectionStatus, CurrentStateAsChangesOptions, Fn, InferSchemaInput, InferSchemaOutput, InsertConfig, NonSingleResult, OperationConfig, SingleResult, SubscribeChangesOptions, Transaction as TransactionType, UtilsRecord, WritableDeep } from '../types.js';
 import { SingleRowRefProxy } from '../query/builder/ref-proxy.js';
 import { StandardSchemaV1 } from '@standard-schema/spec';
 import { BTreeIndex } from '../indexes/btree-index.js';
@@ -16,7 +17,7 @@ import { IndexProxy } from '../indexes/lazy-index.js';
  * @template TUtils - The utilities record type
  * @template TInsertInput - The type for insert operations (can be different from T for schemas with defaults)
  */
-export interface Collection<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}, TSchema extends StandardSchemaV1 = StandardSchemaV1, TInsertInput extends object = T> extends CollectionImpl<T, TKey, TUtils, TSchema, TInsertInput> {
+export interface Collection<T extends object = Record<string, unknown>, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord, TSchema extends StandardSchemaV1 = StandardSchemaV1, TInsertInput extends object = T> extends CollectionImpl<T, TKey, TUtils, TSchema, TInsertInput> {
     readonly utils: TUtils;
     readonly singleResult?: true;
 }
@@ -90,19 +91,19 @@ export interface Collection<T extends object = Record<string, unknown>, TKey ext
  * })
  *
  */
-export declare function createCollection<T extends StandardSchemaV1, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}>(options: CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
+export declare function createCollection<T extends StandardSchemaV1, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord>(options: CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
     schema: T;
     utils?: TUtils;
 } & NonSingleResult): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> & NonSingleResult;
-export declare function createCollection<T extends StandardSchemaV1, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}>(options: CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
+export declare function createCollection<T extends StandardSchemaV1, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord>(options: CollectionConfig<InferSchemaOutput<T>, TKey, T> & {
     schema: T;
     utils?: TUtils;
 } & SingleResult): Collection<InferSchemaOutput<T>, TKey, TUtils, T, InferSchemaInput<T>> & SingleResult;
-export declare function createCollection<T extends object, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}>(options: CollectionConfig<T, TKey, never> & {
+export declare function createCollection<T extends object, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord>(options: CollectionConfig<T, TKey, never> & {
     schema?: never;
     utils?: TUtils;
 } & NonSingleResult): Collection<T, TKey, TUtils, never, T> & NonSingleResult;
-export declare function createCollection<T extends object, TKey extends string | number = string | number, TUtils extends UtilsRecord = {}>(options: CollectionConfig<T, TKey, never> & {
+export declare function createCollection<T extends object, TKey extends string | number = string | number, TUtils extends UtilsRecord = UtilsRecord>(options: CollectionConfig<T, TKey, never> & {
     schema?: never;
     utils?: TUtils;
 } & SingleResult): Collection<T, TKey, TUtils, never, T> & SingleResult;
@@ -113,7 +114,7 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
     private _events;
     private _changes;
     _lifecycle: CollectionLifecycleManager<TOutput, TKey, TSchema, TInput>;
-    private _sync;
+    _sync: CollectionSyncManager<TOutput, TKey, TSchema, TInput>;
     private _indexes;
     private _mutations;
     _state: CollectionStateManager<TOutput, TKey, TSchema, TInput>;
@@ -156,18 +157,16 @@ export declare class CollectionImpl<TOutput extends object = Record<string, unkn
      * }
      */
     isReady(): boolean;
+    /**
+     * Check if the collection is currently loading more data
+     * @returns true if the collection has pending load more operations, false otherwise
+     */
+    get isLoadingSubset(): boolean;
     /**
      * Start sync immediately - internal method for compiled queries
      * This bypasses lazy loading for special cases like live query results
      */
     startSyncImmediate(): void;
-    /**
-     * Requests the sync layer to load more data.
-     * @param options Options to control what data is being loaded
-     * @returns If data loading is asynchronous, this method returns a promise that resolves when the data is loaded.
-     *          If data loading is synchronous, the data is loaded when the method returns.
-     */
-    syncMore(options: OnLoadMoreOptions): void | Promise<void>;
     /**
      * Preload the collection data by starting sync if not already started
      * Multiple concurrent calls will share the same promise

package/dist/esm/collection/index.js

@@ -94,7 +94,8 @@ class CollectionImpl {
       collection: this,
       // Required for passing to config.sync callback
       state: this._state,
-      lifecycle: this._lifecycle
+      lifecycle: this._lifecycle,
+      events: this._events
     });
     if (config.startSync === true) {
       this._sync.startSync();
@@ -140,6 +141,13 @@ class CollectionImpl {
   isReady() {
     return this._lifecycle.status === `ready`;
   }
+  /**
+   * Check if the collection is currently loading more data
+   * @returns true if the collection has pending load more operations, false otherwise
+   */
+  get isLoadingSubset() {
+    return this._sync.isLoadingSubset;
+  }
   /**
    * Start sync immediately - internal method for compiled queries
    * This bypasses lazy loading for special cases like live query results
@@ -147,17 +155,6 @@ class CollectionImpl {
   startSyncImmediate() {
     this._sync.startSync();
   }
-  /**
-   * Requests the sync layer to load more data.
-   * @param options Options to control what data is being loaded
-   * @returns If data loading is asynchronous, this method returns a promise that resolves when the data is loaded.
-   *          If data loading is synchronous, the data is loaded when the method returns.
-   */
-  syncMore(options) {
-    if (this._sync.syncOnLoadMoreFn) {
-      return this._sync.syncOnLoadMoreFn(options);
-    }
-  }
   /**
    * Preload the collection data by starting sync if not already started
    * Multiple concurrent calls will share the same promise