@zuzjs/flare 0.2.6 → 0.2.8

package/dist/index.d.cts

@@ -332,6 +332,58 @@ type DocAddedCallback<T = any> = (data: T, docId: string) => void;
 type DocUpdatedCallback<T = any> = (data: T, docId: string) => void;
 type DocDeletedCallback<T = any> = (docId: string) => void;
 type DocChangedCallback<T = any> = (data: T | null, docId: string, operation: ChangeOperation) => void;
+type StreamFlushReason = 'snapshot' | 'change-batch';
+interface CollectionStreamOptions<T = any> {
+    /** Delay before a queued burst is flushed to listeners. */
+    flushMs?: number;
+    /** Flush immediately when queued changes reach this count. */
+    maxBatchSize?: number;
+    /** Field used to identify docs inside snapshots when getId is not provided. */
+    idField?: keyof T & string;
+    /** Custom identifier extractor for snapshot rows. */
+    getId?: (doc: T) => string | undefined;
+    /** Where newly inserted docs should be placed when they were not in snapshot. */
+    insertAt?: 'start' | 'end';
+    /** Optional cap to keep only the newest N docs in local stream state. */
+    maxDocs?: number;
+    /** Optional local sort run after flush. */
+    sort?: (a: T, b: T) => number;
+}
+interface CollectionStreamMeta {
+    reason: StreamFlushReason;
+    batchSize: number;
+    version: number;
+    ready: boolean;
+}
+type CollectionStreamListener<T = any> = (rows: readonly T[], meta: CollectionStreamMeta) => void;
+interface CollectionStream<T = any> {
+    /** Subscribe to stream updates (call unsubscribe to stop). */
+    subscribe: (listener: CollectionStreamListener<T>, emitCurrent?: boolean) => () => void;
+    /** Returns the latest immutable snapshot of rows. */
+    getSnapshot: () => readonly T[];
+    /** Returns true after the initial snapshot has been received. */
+    isReady: () => boolean;
+    /** Monotonic version incremented on each flush. */
+    getVersion: () => number;
+    /** Stop the underlying realtime subscription and cleanup timers/listeners. */
+    close: () => void;
+    /** Attach subscription-level error handler. */
+    onError: (callback: SubscriptionErrorCallback) => CollectionStream<T>;
+    /** Attach permission-denied handler. */
+    onPermissionDenied: (callback: SubscriptionErrorCallback) => CollectionStream<T>;
+}
+interface CollectionExternalStore<T = any> {
+    /** Standard external-store subscribe signature used by UI store hooks. */
+    subscribe: (onStoreChange: () => void) => () => void;
+    /** Returns current immutable rows snapshot. */
+    getSnapshot: () => readonly T[];
+    /** Server snapshot fallback for SSR-safe store hooks. */
+    getServerSnapshot: () => readonly T[];
+    /** Access to underlying realtime stream for advanced handlers. */
+    stream: CollectionStream<T>;
+    /** Stops realtime stream and detaches listeners. */
+    destroy: () => void;
+}
 interface DocumentSnapshot<T = any> {
     id: string;
     data: T | null;
@@ -431,13 +483,13 @@ declare function parseValue(val: string): any;
 declare class DocumentQueryBuilder<T = any> implements PromiseLike<T | null | void> {
     private client;
     private collection;
-    private legacyId?;
+    private docIdFromRef?;
     private whereCondition?;
     private updateData?;
     private setData?;
     private deleteOp;
     private promise?;
-    constructor(client: FlareClient<any>, collection: string, legacyId?: string | undefined);
+    constructor(client: FlareClient<any>, collection: string, docIdFromRef?: string | undefined);
     /**
      * Set where condition
      */
@@ -455,7 +507,7 @@ declare class DocumentQueryBuilder<T = any> implements PromiseLike<T | null | vo
      */
     delete(): this;
     /**
-     * Get the document ID from where condition or legacy id
+     * Get the document ID from doc() reference or where condition.
      */
     private getDocId;
     /**
@@ -481,9 +533,7 @@ declare class DocumentQueryBuilder<T = any> implements PromiseLike<T | null | vo
     onSnapshot(callback: SubscriptionCallback<T>): () => void;
 }
 
-/**
- * Legacy document reference (for backward compatibility)
- */
+/** Document reference */
 declare class DocumentReference<T = any> {
     private client;
     readonly collection: string;
@@ -496,13 +546,8 @@ declare class DocumentReference<T = any> {
     onSnapshot(callback: SubscriptionCallback<T>): () => void;
     /**
      * Fires when this document is updated / replaced.
-     * Aliases: onDocModified, onDocChange
      */
     onDocUpdated(callback: DocUpdatedCallback<T>): () => void;
-    /** Alias for onDocUpdated */
-    onDocModified(callback: DocUpdatedCallback<T>): () => void;
-    /** Alias for onDocUpdated */
-    onDocChange(callback: DocUpdatedCallback<T>): () => void;
     /**
      * Fires when this document is deleted.
      */
@@ -533,6 +578,9 @@ declare class CollectionReference<T = any, TPresetMap extends QueryPresetMap = {
     private appendAndFilters;
     private toOrNode;
     private toAndNode;
+    private isLeafFilter;
+    private isIdentityGuard;
+    private splitIdentityGuards;
     private appendOrFilters;
     private appendFilters;
     with<Name extends keyof TPresetMap & string>(name: Name, params: QueryPresetParams<TPresetMap[Name]>): CollectionQuery<QueryPresetRow<TPresetMap[Name]>, TPresetMap>;
@@ -570,6 +618,8 @@ declare class CollectionReference<T = any, TPresetMap extends QueryPresetMap = {
     orNotExists(field: string): CollectionQuery<T, TPresetMap>;
     /** Get items starting from the most recently created (descending sequence) */
     latest(): CollectionQuery<T, TPresetMap>;
+    /** Get items starting from the most recently created (descending sequence) */
+    newest(): CollectionQuery<T, TPresetMap>;
     /** Get items starting from the first ever created (ascending sequence) */
     oldest(): CollectionQuery<T, TPresetMap>;
     orderBy(field: string, dir?: "asc" | "desc"): CollectionQuery<T, TPresetMap>;
@@ -589,6 +639,9 @@ declare class CollectionReference<T = any, TPresetMap extends QueryPresetMap = {
     groupBy(...fields: string[]): CollectionQuery<T, TPresetMap>;
     having(field: string, op: HavingClause['op'], value: number): CollectionQuery<T, TPresetMap>;
     private buildStructuredJoin;
+    private cloneStructuredJoin;
+    private appendNestedJoinByAlias;
+    private parseRelationRef;
     /**
      * Join another collection into this query.
      *
@@ -596,19 +649,26 @@ declare class CollectionReference<T = any, TPresetMap extends QueryPresetMap = {
      * @param j Join mapping clause.
      * @example
      *   flare.collection("boards")
-     *     .Join("tasks", { source: "id", target: "boardId", as: "tasks" })
+     *     .join("tasks", { source: "id", target: "boardId", as: "tasks" })
      *     .get();
      */
+    join(collectionName: string, j: JoinClause): CollectionQuery<T, TPresetMap>;
+    /**
+     * Append a nested join under an existing join alias.
+     * Example:
+     *   .join("lists", { source: "id", target: "boardId", as: "lists" })
+     *   .joinNested("lists", "cards", { source: "id", target: "listId", as: "cards" })
+     */
+    joinNested(parentAlias: string, collectionName: string, j: JoinClause): CollectionQuery<T, TPresetMap>;
     Join(collectionName: string, j: JoinClause): CollectionQuery<T, TPresetMap>;
+    JoinNested(parentAlias: string, collectionName: string, j: JoinClause): CollectionQuery<T, TPresetMap>;
     /**
-     * Legacy join signature.
-     * Prefer Join(collectionName, clause) for better readability.
+     * SQL-like relation shorthand.
+     * Example: .withRelation("team.uid->users.id", { as: "teamMembers" })
      */
-    join(collectionName: string, j: JoinClause): CollectionQuery<T, TPresetMap>;
-    join(j: JoinClause & {
-        from?: string;
-        collection?: string;
-    }): CollectionQuery<T, TPresetMap>;
+    withRelation(relation: string, options?: (Omit<JoinClause, 'source' | 'target' | 'as'> & {
+        as?: string;
+    })): CollectionQuery<T, TPresetMap>;
     select(...fields: string[]): CollectionQuery<T, TPresetMap>;
     /** Returns unique values for a single field */
     distinctField(field: string): CollectionQuery<T, TPresetMap>;
@@ -618,6 +678,10 @@ declare class CollectionReference<T = any, TPresetMap extends QueryPresetMap = {
      *   col.vectorSearch({ field: "embedding", vector: [...1536 numbers...], k: 10 })
      */
     vectorSearch(opts: VectorSearchClause): CollectionQuery<T, TPresetMap>;
+    getRawQuery(): {
+        collection: string;
+        query: StructuredQuery;
+    };
     get(): Promise<T[]>;
     private _isStructured;
     private _execute;
@@ -632,10 +696,18 @@ declare class CollectionReference<T = any, TPresetMap extends QueryPresetMap = {
      * the live result consistent.
      */
     onSnapshot(callback: SubscriptionCallback<T[]>): SubscriptionHandle;
+    /**
+     * High-throughput stream wrapper for bursty collections (chat, feeds, logs).
+     * It keeps local state and flushes change bursts in batches to reduce UI churn.
+     */
+    stream(options?: CollectionStreamOptions<T>): CollectionStream<T>;
+    /**
+     * Framework-agnostic external-store bridge.
+     * Compatible with UI hooks expecting subscribe/getSnapshot signatures.
+     */
+    asStore(options?: CollectionStreamOptions<T>): CollectionExternalStore<T>;
     onDocAdded(callback: DocAddedCallback<T>): () => void;
     onDocUpdated(callback: DocUpdatedCallback<T>): () => void;
-    onDocModified(callback: DocUpdatedCallback<T>): () => void;
-    onDocChange(callback: DocUpdatedCallback<T>): () => void;
     onDocDeleted(callback: DocDeletedCallback<T>): () => void;
     onDocChanged(callback: DocChangedCallback<T>): () => void;
     add(data: Partial<T>): Promise<DocumentReference<T>>;
@@ -737,7 +809,7 @@ type ActiveSubscription = {
     liveId: string;
     collection: string;
     docId?: string;
-    query?: QueryConfig | StructuredQuery;
+    query?: StructuredQuery;
     callback: SubscriptionCallback;
     options: SubscribeOptions;
 };
@@ -872,7 +944,7 @@ declare class FlareBase<TPresetMap extends QueryPresetMap = {}> {
     protected toSubscriptionError(err: unknown): SubscriptionError;
     protected emitSubscriptionError(baseId: string, error: SubscriptionError): void;
     protected replayActiveSubscriptions(): Promise<void>;
-    subscribe(subId: string, collection: string, docId: string | undefined, query: QueryConfig | StructuredQuery | undefined, callback: SubscriptionCallback, options?: SubscribeOptions): SubscriptionHandle;
+    subscribe(subId: string, collection: string, docId: string | undefined, query: StructuredQuery | undefined, callback: SubscriptionCallback, options?: SubscribeOptions): SubscriptionHandle;
     send(type: FlareAction, payload: any): Promise<any>;
     private handleTransportError;
     protected onConnected(): void;
@@ -1420,4 +1492,4 @@ declare const getFlare: () => FlareClient | null;
  */
 declare const disconnectFlare: () => void;
 
-export { type AggregateFunction, type AggregateSpec, type AndFilter, type AnyFilter, type AuthConfigListener, type AuthConfigResponse, type AuthResult, type AuthStateListener, type AuthWithPendingVerificationResult, type AuthWithTokenResult, type BaseMessage, type BrowserPushRegistrationOptions, type BrowserPushTokenOptions, type ChangeEvent, type ChangeOperation, type CollectionPresetMethods, type CollectionQuery, CollectionReference, type ConnectionState, type CsrfProxyConfig, type CursorValue, type DocAddedCallback, type DocChangedCallback, type DocDeletedCallback, type DocUpdatedCallback, DocumentQueryBuilder, DocumentReference, type DocumentSnapshot, type EmailLinkVerifyResult, type EmailSendResult, FlareAction, type FlareAuthConfig, type FlareAuthProviderId, type FlareAuthProviderPublicConfig, type FlareAuthSession, type FlareAuthUser, type FlareConfig, FlareError, FlareErrors, FlareEvent, FlareResponseCodes, type FlareRule, type GroupByClause, type HavingClause, type JoinClause, type JoinQueryPattern, type NestedJoinClause, type OfflineOperation, type OrFilter, type OrderByClause, type PresenceCallback, type PresenceJoinCallback, type PresenceLeaveCallback, type PresenceMember, type PushSendResult, type QueryConfig, type QueryOperator, type QueryPresetMap, type QueryPresetParams, type QueryPresetRow, type QueryPresetSpec, type QuerySnapshot, type RegisterPushTokenInput, type RulePermission, type SecurityRuleEntry, type SecurityRulesMap, type SendEmailInput, type SendPushNotificationInput, type SnapshotEvent, type StructuredJoinClause, type StructuredQuery, type SubscribeMessage, type SubscribeOptions, type SubscriptionCallback, type SubscriptionData, type SubscriptionError, type SubscriptionErrorCallback, type SubscriptionHandle, type VectorFieldConfig, type VectorSearchClause, type VerifyEmailLinkInput, type WhereCondition, buildFlareHeaders, connectApp, createCsrfProxy, createCsrfProxyHandler, FlareClient as default, disconnectFlare, extractCsrfFromRequest, flareRulesToSecurityMap, getFlare, parseValue, parseWhereCondition, securityMapToFlareRules };
+export { type AggregateFunction, type AggregateSpec, type AndFilter, type AnyFilter, type AuthConfigListener, type AuthConfigResponse, type AuthResult, type AuthStateListener, type AuthWithPendingVerificationResult, type AuthWithTokenResult, type BaseMessage, type BrowserPushRegistrationOptions, type BrowserPushTokenOptions, type ChangeEvent, type ChangeOperation, type CollectionExternalStore, type CollectionPresetMethods, type CollectionQuery, CollectionReference, type CollectionStream, type CollectionStreamListener, type CollectionStreamMeta, type CollectionStreamOptions, type ConnectionState, type CsrfProxyConfig, type CursorValue, type DocAddedCallback, type DocChangedCallback, type DocDeletedCallback, type DocUpdatedCallback, DocumentQueryBuilder, DocumentReference, type DocumentSnapshot, type EmailLinkVerifyResult, type EmailSendResult, FlareAction, type FlareAuthConfig, type FlareAuthProviderId, type FlareAuthProviderPublicConfig, type FlareAuthSession, type FlareAuthUser, FlareClient, type FlareConfig, FlareError, FlareErrors, FlareEvent, FlareResponseCodes, type FlareRule, type GroupByClause, type HavingClause, type JoinClause, type JoinQueryPattern, type NestedJoinClause, type OfflineOperation, type OrFilter, type OrderByClause, type PresenceCallback, type PresenceJoinCallback, type PresenceLeaveCallback, type PresenceMember, type PushSendResult, type QueryConfig, type QueryOperator, type QueryPresetMap, type QueryPresetParams, type QueryPresetRow, type QueryPresetSpec, type QuerySnapshot, type RegisterPushTokenInput, type RulePermission, type SecurityRuleEntry, type SecurityRulesMap, type SendEmailInput, type SendPushNotificationInput, type SnapshotEvent, type StreamFlushReason, type StructuredJoinClause, type StructuredQuery, type SubscribeMessage, type SubscribeOptions, type SubscriptionCallback, type SubscriptionData, type SubscriptionError, type SubscriptionErrorCallback, type SubscriptionHandle, type VectorFieldConfig, type VectorSearchClause, type VerifyEmailLinkInput, type WhereCondition, buildFlareHeaders, connectApp, createCsrfProxy, createCsrfProxyHandler, disconnectFlare, extractCsrfFromRequest, flareRulesToSecurityMap, getFlare, parseValue, parseWhereCondition, securityMapToFlareRules };

package/dist/index.d.ts

@@ -332,6 +332,58 @@ type DocAddedCallback<T = any> = (data: T, docId: string) => void;
 type DocUpdatedCallback<T = any> = (data: T, docId: string) => void;
 type DocDeletedCallback<T = any> = (docId: string) => void;
 type DocChangedCallback<T = any> = (data: T | null, docId: string, operation: ChangeOperation) => void;
+type StreamFlushReason = 'snapshot' | 'change-batch';
+interface CollectionStreamOptions<T = any> {
+    /** Delay before a queued burst is flushed to listeners. */
+    flushMs?: number;
+    /** Flush immediately when queued changes reach this count. */
+    maxBatchSize?: number;
+    /** Field used to identify docs inside snapshots when getId is not provided. */
+    idField?: keyof T & string;
+    /** Custom identifier extractor for snapshot rows. */
+    getId?: (doc: T) => string | undefined;
+    /** Where newly inserted docs should be placed when they were not in snapshot. */
+    insertAt?: 'start' | 'end';
+    /** Optional cap to keep only the newest N docs in local stream state. */
+    maxDocs?: number;
+    /** Optional local sort run after flush. */
+    sort?: (a: T, b: T) => number;
+}
+interface CollectionStreamMeta {
+    reason: StreamFlushReason;
+    batchSize: number;
+    version: number;
+    ready: boolean;
+}
+type CollectionStreamListener<T = any> = (rows: readonly T[], meta: CollectionStreamMeta) => void;
+interface CollectionStream<T = any> {
+    /** Subscribe to stream updates (call unsubscribe to stop). */
+    subscribe: (listener: CollectionStreamListener<T>, emitCurrent?: boolean) => () => void;
+    /** Returns the latest immutable snapshot of rows. */
+    getSnapshot: () => readonly T[];
+    /** Returns true after the initial snapshot has been received. */
+    isReady: () => boolean;
+    /** Monotonic version incremented on each flush. */
+    getVersion: () => number;
+    /** Stop the underlying realtime subscription and cleanup timers/listeners. */
+    close: () => void;
+    /** Attach subscription-level error handler. */
+    onError: (callback: SubscriptionErrorCallback) => CollectionStream<T>;
+    /** Attach permission-denied handler. */
+    onPermissionDenied: (callback: SubscriptionErrorCallback) => CollectionStream<T>;
+}
+interface CollectionExternalStore<T = any> {
+    /** Standard external-store subscribe signature used by UI store hooks. */
+    subscribe: (onStoreChange: () => void) => () => void;
+    /** Returns current immutable rows snapshot. */
+    getSnapshot: () => readonly T[];
+    /** Server snapshot fallback for SSR-safe store hooks. */
+    getServerSnapshot: () => readonly T[];
+    /** Access to underlying realtime stream for advanced handlers. */
+    stream: CollectionStream<T>;
+    /** Stops realtime stream and detaches listeners. */
+    destroy: () => void;
+}
 interface DocumentSnapshot<T = any> {
     id: string;
     data: T | null;
@@ -431,13 +483,13 @@ declare function parseValue(val: string): any;
 declare class DocumentQueryBuilder<T = any> implements PromiseLike<T | null | void> {
     private client;
     private collection;
-    private legacyId?;
+    private docIdFromRef?;
     private whereCondition?;
     private updateData?;
     private setData?;
     private deleteOp;
     private promise?;
-    constructor(client: FlareClient<any>, collection: string, legacyId?: string | undefined);
+    constructor(client: FlareClient<any>, collection: string, docIdFromRef?: string | undefined);
     /**
      * Set where condition
      */
@@ -455,7 +507,7 @@ declare class DocumentQueryBuilder<T = any> implements PromiseLike<T | null | vo
      */
     delete(): this;
     /**
-     * Get the document ID from where condition or legacy id
+     * Get the document ID from doc() reference or where condition.
      */
     private getDocId;
     /**
@@ -481,9 +533,7 @@ declare class DocumentQueryBuilder<T = any> implements PromiseLike<T | null | vo
     onSnapshot(callback: SubscriptionCallback<T>): () => void;
 }
 
-/**
- * Legacy document reference (for backward compatibility)
- */
+/** Document reference */
 declare class DocumentReference<T = any> {
     private client;
     readonly collection: string;
@@ -496,13 +546,8 @@ declare class DocumentReference<T = any> {
     onSnapshot(callback: SubscriptionCallback<T>): () => void;
     /**
      * Fires when this document is updated / replaced.
-     * Aliases: onDocModified, onDocChange
      */
     onDocUpdated(callback: DocUpdatedCallback<T>): () => void;
-    /** Alias for onDocUpdated */
-    onDocModified(callback: DocUpdatedCallback<T>): () => void;
-    /** Alias for onDocUpdated */
-    onDocChange(callback: DocUpdatedCallback<T>): () => void;
     /**
      * Fires when this document is deleted.
      */
@@ -533,6 +578,9 @@ declare class CollectionReference<T = any, TPresetMap extends QueryPresetMap = {
     private appendAndFilters;
     private toOrNode;
     private toAndNode;
+    private isLeafFilter;
+    private isIdentityGuard;
+    private splitIdentityGuards;
     private appendOrFilters;
     private appendFilters;
     with<Name extends keyof TPresetMap & string>(name: Name, params: QueryPresetParams<TPresetMap[Name]>): CollectionQuery<QueryPresetRow<TPresetMap[Name]>, TPresetMap>;
@@ -570,6 +618,8 @@ declare class CollectionReference<T = any, TPresetMap extends QueryPresetMap = {
     orNotExists(field: string): CollectionQuery<T, TPresetMap>;
     /** Get items starting from the most recently created (descending sequence) */
     latest(): CollectionQuery<T, TPresetMap>;
+    /** Get items starting from the most recently created (descending sequence) */
+    newest(): CollectionQuery<T, TPresetMap>;
     /** Get items starting from the first ever created (ascending sequence) */
     oldest(): CollectionQuery<T, TPresetMap>;
     orderBy(field: string, dir?: "asc" | "desc"): CollectionQuery<T, TPresetMap>;
@@ -589,6 +639,9 @@ declare class CollectionReference<T = any, TPresetMap extends QueryPresetMap = {
     groupBy(...fields: string[]): CollectionQuery<T, TPresetMap>;
     having(field: string, op: HavingClause['op'], value: number): CollectionQuery<T, TPresetMap>;
     private buildStructuredJoin;
+    private cloneStructuredJoin;
+    private appendNestedJoinByAlias;
+    private parseRelationRef;
     /**
      * Join another collection into this query.
      *
@@ -596,19 +649,26 @@ declare class CollectionReference<T = any, TPresetMap extends QueryPresetMap = {
      * @param j Join mapping clause.
      * @example
      *   flare.collection("boards")
-     *     .Join("tasks", { source: "id", target: "boardId", as: "tasks" })
+     *     .join("tasks", { source: "id", target: "boardId", as: "tasks" })
      *     .get();
      */
+    join(collectionName: string, j: JoinClause): CollectionQuery<T, TPresetMap>;
+    /**
+     * Append a nested join under an existing join alias.
+     * Example:
+     *   .join("lists", { source: "id", target: "boardId", as: "lists" })
+     *   .joinNested("lists", "cards", { source: "id", target: "listId", as: "cards" })
+     */
+    joinNested(parentAlias: string, collectionName: string, j: JoinClause): CollectionQuery<T, TPresetMap>;
     Join(collectionName: string, j: JoinClause): CollectionQuery<T, TPresetMap>;
+    JoinNested(parentAlias: string, collectionName: string, j: JoinClause): CollectionQuery<T, TPresetMap>;
     /**
-     * Legacy join signature.
-     * Prefer Join(collectionName, clause) for better readability.
+     * SQL-like relation shorthand.
+     * Example: .withRelation("team.uid->users.id", { as: "teamMembers" })
      */
-    join(collectionName: string, j: JoinClause): CollectionQuery<T, TPresetMap>;
-    join(j: JoinClause & {
-        from?: string;
-        collection?: string;
-    }): CollectionQuery<T, TPresetMap>;
+    withRelation(relation: string, options?: (Omit<JoinClause, 'source' | 'target' | 'as'> & {
+        as?: string;
+    })): CollectionQuery<T, TPresetMap>;
     select(...fields: string[]): CollectionQuery<T, TPresetMap>;
     /** Returns unique values for a single field */
     distinctField(field: string): CollectionQuery<T, TPresetMap>;
@@ -618,6 +678,10 @@ declare class CollectionReference<T = any, TPresetMap extends QueryPresetMap = {
      *   col.vectorSearch({ field: "embedding", vector: [...1536 numbers...], k: 10 })
      */
     vectorSearch(opts: VectorSearchClause): CollectionQuery<T, TPresetMap>;
+    getRawQuery(): {
+        collection: string;
+        query: StructuredQuery;
+    };
     get(): Promise<T[]>;
     private _isStructured;
     private _execute;
@@ -632,10 +696,18 @@ declare class CollectionReference<T = any, TPresetMap extends QueryPresetMap = {
      * the live result consistent.
      */
     onSnapshot(callback: SubscriptionCallback<T[]>): SubscriptionHandle;
+    /**
+     * High-throughput stream wrapper for bursty collections (chat, feeds, logs).
+     * It keeps local state and flushes change bursts in batches to reduce UI churn.
+     */
+    stream(options?: CollectionStreamOptions<T>): CollectionStream<T>;
+    /**
+     * Framework-agnostic external-store bridge.
+     * Compatible with UI hooks expecting subscribe/getSnapshot signatures.
+     */
+    asStore(options?: CollectionStreamOptions<T>): CollectionExternalStore<T>;
     onDocAdded(callback: DocAddedCallback<T>): () => void;
     onDocUpdated(callback: DocUpdatedCallback<T>): () => void;
-    onDocModified(callback: DocUpdatedCallback<T>): () => void;
-    onDocChange(callback: DocUpdatedCallback<T>): () => void;
     onDocDeleted(callback: DocDeletedCallback<T>): () => void;
     onDocChanged(callback: DocChangedCallback<T>): () => void;
     add(data: Partial<T>): Promise<DocumentReference<T>>;
@@ -737,7 +809,7 @@ type ActiveSubscription = {
     liveId: string;
     collection: string;
     docId?: string;
-    query?: QueryConfig | StructuredQuery;
+    query?: StructuredQuery;
     callback: SubscriptionCallback;
     options: SubscribeOptions;
 };
@@ -872,7 +944,7 @@ declare class FlareBase<TPresetMap extends QueryPresetMap = {}> {
     protected toSubscriptionError(err: unknown): SubscriptionError;
     protected emitSubscriptionError(baseId: string, error: SubscriptionError): void;
     protected replayActiveSubscriptions(): Promise<void>;
-    subscribe(subId: string, collection: string, docId: string | undefined, query: QueryConfig | StructuredQuery | undefined, callback: SubscriptionCallback, options?: SubscribeOptions): SubscriptionHandle;
+    subscribe(subId: string, collection: string, docId: string | undefined, query: StructuredQuery | undefined, callback: SubscriptionCallback, options?: SubscribeOptions): SubscriptionHandle;
     send(type: FlareAction, payload: any): Promise<any>;
     private handleTransportError;
     protected onConnected(): void;
@@ -1420,4 +1492,4 @@ declare const getFlare: () => FlareClient | null;
  */
 declare const disconnectFlare: () => void;
 
-export { type AggregateFunction, type AggregateSpec, type AndFilter, type AnyFilter, type AuthConfigListener, type AuthConfigResponse, type AuthResult, type AuthStateListener, type AuthWithPendingVerificationResult, type AuthWithTokenResult, type BaseMessage, type BrowserPushRegistrationOptions, type BrowserPushTokenOptions, type ChangeEvent, type ChangeOperation, type CollectionPresetMethods, type CollectionQuery, CollectionReference, type ConnectionState, type CsrfProxyConfig, type CursorValue, type DocAddedCallback, type DocChangedCallback, type DocDeletedCallback, type DocUpdatedCallback, DocumentQueryBuilder, DocumentReference, type DocumentSnapshot, type EmailLinkVerifyResult, type EmailSendResult, FlareAction, type FlareAuthConfig, type FlareAuthProviderId, type FlareAuthProviderPublicConfig, type FlareAuthSession, type FlareAuthUser, type FlareConfig, FlareError, FlareErrors, FlareEvent, FlareResponseCodes, type FlareRule, type GroupByClause, type HavingClause, type JoinClause, type JoinQueryPattern, type NestedJoinClause, type OfflineOperation, type OrFilter, type OrderByClause, type PresenceCallback, type PresenceJoinCallback, type PresenceLeaveCallback, type PresenceMember, type PushSendResult, type QueryConfig, type QueryOperator, type QueryPresetMap, type QueryPresetParams, type QueryPresetRow, type QueryPresetSpec, type QuerySnapshot, type RegisterPushTokenInput, type RulePermission, type SecurityRuleEntry, type SecurityRulesMap, type SendEmailInput, type SendPushNotificationInput, type SnapshotEvent, type StructuredJoinClause, type StructuredQuery, type SubscribeMessage, type SubscribeOptions, type SubscriptionCallback, type SubscriptionData, type SubscriptionError, type SubscriptionErrorCallback, type SubscriptionHandle, type VectorFieldConfig, type VectorSearchClause, type VerifyEmailLinkInput, type WhereCondition, buildFlareHeaders, connectApp, createCsrfProxy, createCsrfProxyHandler, FlareClient as default, disconnectFlare, extractCsrfFromRequest, flareRulesToSecurityMap, getFlare, parseValue, parseWhereCondition, securityMapToFlareRules };
+export { type AggregateFunction, type AggregateSpec, type AndFilter, type AnyFilter, type AuthConfigListener, type AuthConfigResponse, type AuthResult, type AuthStateListener, type AuthWithPendingVerificationResult, type AuthWithTokenResult, type BaseMessage, type BrowserPushRegistrationOptions, type BrowserPushTokenOptions, type ChangeEvent, type ChangeOperation, type CollectionExternalStore, type CollectionPresetMethods, type CollectionQuery, CollectionReference, type CollectionStream, type CollectionStreamListener, type CollectionStreamMeta, type CollectionStreamOptions, type ConnectionState, type CsrfProxyConfig, type CursorValue, type DocAddedCallback, type DocChangedCallback, type DocDeletedCallback, type DocUpdatedCallback, DocumentQueryBuilder, DocumentReference, type DocumentSnapshot, type EmailLinkVerifyResult, type EmailSendResult, FlareAction, type FlareAuthConfig, type FlareAuthProviderId, type FlareAuthProviderPublicConfig, type FlareAuthSession, type FlareAuthUser, FlareClient, type FlareConfig, FlareError, FlareErrors, FlareEvent, FlareResponseCodes, type FlareRule, type GroupByClause, type HavingClause, type JoinClause, type JoinQueryPattern, type NestedJoinClause, type OfflineOperation, type OrFilter, type OrderByClause, type PresenceCallback, type PresenceJoinCallback, type PresenceLeaveCallback, type PresenceMember, type PushSendResult, type QueryConfig, type QueryOperator, type QueryPresetMap, type QueryPresetParams, type QueryPresetRow, type QueryPresetSpec, type QuerySnapshot, type RegisterPushTokenInput, type RulePermission, type SecurityRuleEntry, type SecurityRulesMap, type SendEmailInput, type SendPushNotificationInput, type SnapshotEvent, type StreamFlushReason, type StructuredJoinClause, type StructuredQuery, type SubscribeMessage, type SubscribeOptions, type SubscriptionCallback, type SubscriptionData, type SubscriptionError, type SubscriptionErrorCallback, type SubscriptionHandle, type VectorFieldConfig, type VectorSearchClause, type VerifyEmailLinkInput, type WhereCondition, buildFlareHeaders, connectApp, createCsrfProxy, createCsrfProxyHandler, disconnectFlare, extractCsrfFromRequest, flareRulesToSecurityMap, getFlare, parseValue, parseWhereCondition, securityMapToFlareRules };