@multiplatform.one/frappe 6.0.4 → 6.3.0

package/types/frappeReact.d.ts

@@ -0,0 +1,270 @@
+import type { Collection } from "@tanstack/db";
+import { type FrappeCollectionOptionsConfig } from "./collection";
+import { SyncModule } from "./sync";
+/**
+ * Configuration for creating a Frappe collection with connection details.
+ */
+export interface UseFrappeCollectionConfig {
+    /** The base URL of the Frappe server */
+    baseURL: string;
+    /**
+     * Override the port used for the Socket.IO realtime connection.
+     * In dev, set to `FRAPPE_SOCKETIO_PORT` (e.g. 9000).  Omit in production
+     * behind a reverse proxy so the base URL port is used.
+     */
+    socketPort?: number;
+    /** Authentication configuration */
+    auth?: {
+        useToken?: boolean;
+        token?: string | (() => string | Promise<string>);
+        type?: string;
+        /** Session id for Socket.IO cookie auth on Node / React Native */
+        sessionId?: string | (() => string | Promise<string>);
+    };
+    /** Sync options for the SyncModule */
+    syncOptions?: import("./sync/types").SyncOptions;
+    /**
+     * Extra Socket.IO client options merged over the defaults — e.g.
+     * `{ transports: ["polling", "websocket"] }` behind dev proxies that can't
+     * forward WebSocket upgrades (websocket-first would never connect there).
+     */
+    socketOptions?: import("./realtime").RealtimeConfig["socketOptions"];
+    /** Fixture provider for testing (used by frappe-ui in development) */
+    fixtures?: import("./fixtures").FixtureProvider;
+}
+/**
+ * Returns the first active SyncModule, or undefined if none exist.
+ * Intended for devtools integration — not part of the public API.
+ */
+export declare function __getActiveSyncModule(): SyncModule | undefined;
+/**
+ * React hook that returns a TanStack DB Collection backed by a Frappe doctype.
+ *
+ * Collections are shared: every hook instance with the same connection,
+ * doctype, and options (fields/filters/orderBy/limit/id) receives the SAME
+ * collection instance backed by ONE SyncModule subscription and ONE realtime
+ * room. Instances are refcounted — the shared collection is cleaned up
+ * shortly after the last consumer unmounts. `onSyncError` callbacks are
+ * per-consumer: each mounted consumer's handler fires (replayed on retain
+ * for late mounts). A failed initial sync is HELD by the entry while any
+ * consumer retains it — error-state re-renders reuse the same errored
+ * collection instead of looping fresh failing syncs — and the entry is
+ * evicted when the last consumer releases it, so the next mount (an
+ * explicit Retry remount) starts exactly one fresh attempt.
+ *
+ * The collection is stable across re-renders. It can be used with
+ * `useLiveQuery` for reactive queries and has `.insert()`, `.update()`,
+ * `.delete()` methods for mutations.
+ *
+ * @typeParam TDoc - The Frappe document type
+ * @param config - Connection configuration (baseURL, auth)
+ * @param doctype - The Frappe doctype name
+ * @param options - Optional collection configuration (fields, filters, etc.)
+ * @returns A stable TanStack DB Collection instance, or undefined if config is not provided
+ *
+ * @example
+ * ```tsx
+ * function PokemonList() {
+ *   const config = useFrappeConfig();
+ *   const collection = useFrappeCollection<Pokemon>(
+ *     config ? { baseURL: config.baseURL, auth: config.auth } : undefined,
+ *     "Pokemon",
+ *     { fields: ["name", "pokemon_name", "poke_id"] }
+ *   );
+ *
+ *   const { data, isLoading } = useLiveQuery(
+ *     (q) => collection ? q.from({ pokemon: collection }) : null,
+ *     [collection]
+ *   );
+ *
+ *   if (isLoading) return <Spinner />;
+ *   return data?.map(p => <div key={p.name}>{p.pokemon_name}</div>);
+ * }
+ * ```
+ */
+export declare function useFrappeCollection<TDoc extends object & {
+    name: string;
+    doctype: string;
+}>(config: UseFrappeCollectionConfig | undefined, doctype: string, options?: Omit<FrappeCollectionOptionsConfig<TDoc>, "sync">): Collection<TDoc, string> | undefined;
+/** Snapshot returned by {@link useFrappeConnection}. */
+export interface FrappeConnectionState {
+    /** Socket connected right now. */
+    connected: boolean;
+    /** Socket has connected at least once this session. */
+    everConnected: boolean;
+}
+/**
+ * React hook exposing the realtime socket state for the given connection.
+ *
+ * `connected` flips on every socket connect/disconnect; `everConnected`
+ * distinguishes "reconnecting" (show an indicator) from "realtime was never
+ * up" (fixture mode / SSR / no socket — show nothing). Fixture-backed
+ * configs always report disconnected/never-connected.
+ */
+export declare function useFrappeConnection(config: UseFrappeCollectionConfig | undefined): FrappeConnectionState;
+/**
+ * React hook that joins a doctype's realtime room and invokes `onEvent`
+ * for every realtime event targeting that doctype (doc_update, list_update,
+ * doc_deleted). Intended for consumers that manage their own fetching
+ * (e.g. server-side paginated tables) and want live invalidation hints.
+ *
+ * The handler is kept in a ref, so an inline function is fine.
+ */
+export declare function useFrappeDoctypeEvents(config: UseFrappeCollectionConfig | undefined, doctype: string, onEvent: (event: {
+    type: string;
+    payload?: unknown;
+}) => void, enabled?: boolean): void;
+/**
+ * Configuration for the useInfiniteScroll hook
+ */
+export interface UseInfiniteScrollConfig {
+    /** Whether more data is available to load */
+    hasMore: boolean;
+    /** Whether data is currently being loaded */
+    isLoading: boolean;
+    /** Function to call when more data should be loaded */
+    onLoadMore: () => void | Promise<void>;
+    /** Root element for intersection (default: viewport) */
+    root?: Element | null;
+    /** Margin around the root (default: "100px") */
+    rootMargin?: string;
+    /** Visibility threshold 0-1 (default: 0.1) */
+    threshold?: number;
+    /** Debounce delay in ms (default: 100) */
+    debounceMs?: number;
+    /** Enable/disable the hook (default: true) */
+    enabled?: boolean;
+}
+/**
+ * Result from the useInfiniteScroll hook
+ */
+export interface UseInfiniteScrollResult {
+    /** Ref to attach to the sentinel element */
+    sentinelRef: React.RefCallback<Element | null>;
+    /** Whether the sentinel is currently visible */
+    isVisible: boolean;
+    /** Whether load more is in progress */
+    isLoadingMore: boolean;
+}
+/**
+ * React hook for automatic infinite scroll loading.
+ *
+ * Uses IntersectionObserver to detect when a sentinel element becomes visible
+ * and automatically triggers loading of more data. Includes debouncing to prevent
+ * rapid-fire requests.
+ *
+ * @param config - Configuration options
+ * @returns Object with sentinelRef to attach to your loading indicator element
+ *
+ * @example
+ * ```tsx
+ * function PokemonList() {
+ *   const [page, setPage] = useState(1);
+ *   const { data, hasMore, isLoading } = usePokemonList(page);
+ *
+ *   const { sentinelRef, isLoadingMore } = useInfiniteScroll({
+ *     hasMore,
+ *     isLoading,
+ *     onLoadMore: () => setPage(p => p + 1),
+ *   });
+ *
+ *   return (
+ *     <div>
+ *       {data.map(pokemon => <PokemonCard key={pokemon.name} {...pokemon} />)}
+ *       <div ref={sentinelRef}>
+ *         {isLoadingMore ? <Spinner /> : hasMore ? "Scroll for more" : "No more items"}
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useInfiniteScroll(config: UseInfiniteScrollConfig): UseInfiniteScrollResult;
+/**
+ * Options for the useFrappeInfiniteList hook
+ */
+export interface UseFrappeInfiniteListConfig<TDoc> {
+    /** Frappe connection configuration */
+    config: UseFrappeCollectionConfig | undefined;
+    /** DocType to query */
+    doctype: string;
+    /** Fields to fetch */
+    fields?: string[];
+    /** Filters to apply */
+    filters?: Array<[string, string, unknown]> | Record<string, unknown>;
+    /** Order by specification */
+    orderBy?: import("./sync/types").OrderBy;
+    /** Page size (default: 20) */
+    pageSize?: number;
+    /** Transform function for items */
+    transform?: (doc: TDoc) => TDoc;
+}
+/**
+ * Result from useFrappeInfiniteList hook
+ */
+export interface UseFrappeInfiniteListResult<TDoc> {
+    /** All loaded items */
+    items: TDoc[];
+    /** Whether more items are available */
+    hasMore: boolean;
+    /** Whether initial load is in progress */
+    isLoading: boolean;
+    /** Whether loading more is in progress */
+    isLoadingMore: boolean;
+    /** Any error that occurred */
+    error: Error | null;
+    /** Ref to attach to sentinel element */
+    sentinelRef: React.RefCallback<Element | null>;
+    /** Manually trigger loading more */
+    loadMore: () => Promise<void>;
+    /** Refresh the list from the beginning */
+    refresh: () => Promise<void>;
+    /** Total number of loaded items */
+    totalLoaded: number;
+}
+/**
+ * React hook for infinite scrolling through a Frappe doctype list.
+ *
+ * Uses SyncModule with progressive subscriptions so that infinite-scroll
+ * lists automatically receive realtime updates, optimistic mutations,
+ * offline support, and CDC backfill -- all features that were previously
+ * only available to `useFrappeCollection` consumers.
+ *
+ * @typeParam TDoc - The document type
+ * @param options - Configuration options
+ * @returns Object with items, loading states, and sentinelRef
+ *
+ * @example
+ * ```tsx
+ * function PokemonList() {
+ *   const config = useFrappeConfig();
+ *   const {
+ *     items,
+ *     hasMore,
+ *     isLoading,
+ *     sentinelRef,
+ *   } = useFrappeInfiniteList<Pokemon>({
+ *     config,
+ *     doctype: "Pokemon",
+ *     fields: ["name", "pokemon_name", "poke_id"],
+ *     pageSize: 20,
+ *   });
+ *
+ *   if (isLoading && items.length === 0) return <Spinner />;
+ *
+ *   return (
+ *     <div>
+ *       {items.map(pokemon => <PokemonCard key={pokemon.name} {...pokemon} />)}
+ *       <div ref={sentinelRef}>
+ *         {hasMore ? <Spinner /> : "No more pokemon"}
+ *       </div>
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useFrappeInfiniteList<TDoc extends object & {
+    name: string;
+    doctype: string;
+}>(options: UseFrappeInfiniteListConfig<TDoc>): UseFrappeInfiniteListResult<TDoc>;
+//# sourceMappingURL=frappeReact.d.ts.map

package/types/frappeReact.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"frappeReact.d.ts","sourceRoot":"","sources":["../src/frappeReact.ts"],"names":[],"mappings":"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"}

package/types/index.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Frappe SDK with TanStack DB Integration
+ *
+ * Production-ready SDK with modular architecture and enterprise features.
+ * Uses TanStack DB for reactive collections, live queries, and optimistic mutations.
+ */
+export { FrappeApp } from "./frappeApp";
+export type { FrappeConfig } from "./frappeApp";
+export { AuthModule } from "./auth";
+export { CallModule } from "./call";
+export { DbModule } from "./db";
+export { FileModule } from "./file";
+export { RealtimeModule } from "./realtime";
+export { SyncModule } from "./sync";
+export { createFrappeCollection, frappeCollectionOptions, createFixtureCollection, fixtureCollectionOptions, } from "./collection";
+export type { FrappeCollectionOptionsConfig, FixtureCollectionOptionsConfig } from "./collection";
+export { createOptimisticAction } from "./optimistic";
+export { useFrappeCollection, useFrappeConnection, useFrappeDoctypeEvents, useInfiniteScroll, useFrappeInfiniteList, __getActiveSyncModule, } from "./frappeReact";
+export type { FrappeConnectionState, UseFrappeCollectionConfig, UseInfiniteScrollConfig, UseInfiniteScrollResult, UseFrappeInfiniteListConfig, UseFrappeInfiniteListResult, } from "./frappeReact";
+export type { SyncRealtimeEvent } from "./sync";
+export { useDebouncedSearch, useThrottledPagination, createRateLimitedBatch } from "./pacer";
+export type { DebouncedSearchOptions, DebouncedSearchResult, FrappeConnectionConfig, ThrottledPaginationOptions, ThrottledPaginationResult, RateLimitedBatchOptions, RateLimitedBatchHandle, } from "./pacer";
+export { useLiveQuery } from "./useLiveQuery";
+export { createCollection, createTransaction } from "@tanstack/db";
+export { eq, gt, gte, lt, lte, and, or, not, inArray, like, ilike, isUndefined, isNull, count, avg, sum, min, max, } from "@tanstack/db";
+export { Debouncer, AsyncDebouncer, Throttler, AsyncThrottler, RateLimiter, AsyncRateLimiter, Queuer, AsyncQueuer, Batcher, AsyncBatcher, debounce, asyncDebounce, throttle, asyncThrottle, rateLimit, asyncRateLimit, queue, asyncQueue, batch, asyncBatch, } from "@tanstack/pacer";
+export * from "./fixtures";
+export { HttpClient, getCookie, setCookie, deleteCookie, setSSRCookies, clearSSRCookies, invalidateCookieCache, } from "./core/http";
+export { FrappeError } from "./core/types";
+export type { AuthConfig, ListOptions, CustomEndpoints, FrappeLiveConfig } from "./core/types";
+export type { BackfillArgs, BackfillResponse, CursorPaginationArgs, CursorPaginationResponse, BatchMutationType, BatchMutation, BatchMutationsArgs, BatchMutationResult, BatchMutationsResponse, ListSinceArgs, ListSinceResponse, } from "./db";
+export { useDocTypeMeta, useLinkSearch, useLinkTitle, useDocTypeSearch, parseDependsOn, parseFormLayout, } from "./doctype";
+export type { DocTypeMeta, DocTypeField, DocTypePermission, FormSection, FormColumn, FrappeFieldType, LinkSearchResult, LinkSearchOptions, DocTypeSearchResult, } from "./doctype";
+export type { FrappeDocValue, FrappeDocData, FrappeDoc, ChildTableRow } from "./common/types";
+export type { SyncOptions, PageBoundaries, RehydrationStrategy, Mutation, ConnectionConfig, TabCoordinationConfig, TabMessage, FrappeDebugState, DebugSubscription, DebugMutationEntry, PageIsland, } from "./sync/types";
+export { Order } from "./sync/types";
+export { MergeStrategy, FieldMergeStrategy } from "./sync/merge";
+export type { FieldMergeStrategyOrFunction, MergeConfig, MergeResult } from "./sync/merge";
+export { matchesFilters, validateFilters, normalizeFilters, extractFilterFields, extractSingleName, formatFilter, hasServerOnlyOperators, canEvaluateClientSide, isTreeOperator, getClientEvaluationBlockers, FilterOperator, } from "./sync/filters";
+export type { Filters, FilterTuple, FilterObject, FilterValue, FilterValidationResult, FilterValidationError, } from "./sync/filters";
+export { TreeDbModule } from "./db";
+export type { GetTreeChildrenArgs, GetTreeAncestorsArgs, GetTreeDescendantsArgs, TreeNode, } from "./db";
+export { default as frappePlugin } from "./plugin";
+//# sourceMappingURL=index.d.ts.map

package/types/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/types/optimistic.d.ts

@@ -0,0 +1,38 @@
+import { createOptimisticAction as tanstackCreateOptimisticAction } from "@tanstack/db";
+export { tanstackCreateOptimisticAction as createOptimisticAction };
+/**
+ * Re-export of TanStack DB's `createOptimisticAction`.
+ *
+ * Creates an optimistic action that applies local state changes immediately
+ * before the server mutation executes. When the mutation completes, the
+ * optimistic state is replaced by the server-confirmed data. On failure,
+ * the optimistic change is rolled back.
+ *
+ * @example
+ * ```typescript
+ * import { createOptimisticAction } from "@multiplatform.one/frappe";
+ *
+ * const addPokemon = createOptimisticAction<Partial<Pokemon>>({
+ *   onMutate: (data) => {
+ *     pokemonCollection.insert({
+ *       name: data.name ?? crypto.randomUUID(),
+ *       doctype: "Pokemon",
+ *       ...data,
+ *     });
+ *   },
+ *   mutationFn: async (data) => {
+ *     await fetch("/api/resource/Pokemon", {
+ *       method: "POST",
+ *       body: JSON.stringify(data),
+ *     });
+ *     // Wait for sync to pick up the new doc before returning
+ *     // so the optimistic state can be safely dropped
+ *   },
+ * });
+ *
+ * // Usage
+ * const tx = addPokemon({ name: "pikachu", pokemon_name: "Pikachu", poke_id: 25 });
+ * await tx.isPersisted.promise;
+ * ```
+ */
+//# sourceMappingURL=optimistic.d.ts.map

package/types/optimistic.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"optimistic.d.ts","sourceRoot":"","sources":["../src/optimistic.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,sBAAsB,IAAI,8BAA8B,EAAE,MAAM,cAAc,CAAC;AAExF,OAAO,EAAE,8BAA8B,IAAI,sBAAsB,EAAE,CAAC;AAEpE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAkCG"}

package/types/pacer.d.ts

@@ -0,0 +1,193 @@
+import type { Collection } from "@tanstack/db";
+import type { FrappeDoc, FrappeDocData } from "./common/types";
+import type { SyncModule } from "./sync";
+/**
+ * Options for `useDebouncedSearch`.
+ */
+export interface DebouncedSearchOptions<TDoc extends FrappeDocData> {
+    /** Debounce delay in milliseconds (default 300) */
+    wait?: number;
+    /** Fields to return from the search */
+    fields?: readonly (keyof TDoc & string)[];
+    /** Additional static filters merged into every request */
+    filters?: Record<string, unknown> | Array<[string, string, unknown]>;
+    /** Maximum results per search (default 20) */
+    limit?: number;
+    /** Minimum query length before firing a search (default 1) */
+    minLength?: number;
+    /** Field to match against with `like` (default "name") */
+    searchField?: string;
+}
+/**
+ * Return type of `useDebouncedSearch`.
+ */
+export interface DebouncedSearchResult<TDoc extends FrappeDocData> {
+    /** Current query string */
+    query: string;
+    /** Set the search query (triggers debounced search) */
+    setQuery: (query: string) => void;
+    /** Search results from the most recent completed search */
+    results: FrappeDoc<TDoc>[];
+    /** Whether a search API call is in-flight */
+    isSearching: boolean;
+    /** Cancel any pending debounced search */
+    cancel: () => void;
+}
+/**
+ * Connection configuration for hooks that need a Frappe backend.
+ */
+export interface FrappeConnectionConfig {
+    /** The base URL of the Frappe server */
+    baseURL: string;
+    /** Override port for Socket.IO realtime connection (e.g. 9000 in dev). */
+    socketPort?: number;
+    /** Authentication configuration */
+    auth?: {
+        useToken?: boolean;
+        token?: string | (() => string | Promise<string>);
+        type?: string;
+    };
+}
+/**
+ * Debounced search hook for Frappe doctypes.
+ *
+ * Uses TanStack Pacer's `AsyncDebouncer` to debounce user input before
+ * firing a `getDocList` API call with a `like` filter.
+ *
+ * @typeParam TDoc - The Frappe document type
+ * @param config - Connection configuration (baseURL, auth), or undefined to disable
+ * @param doctype - The Frappe doctype to search
+ * @param options - Search options (wait, fields, filters, limit, minLength, searchField)
+ * @returns `{ query, setQuery, results, isSearching, cancel }`
+ *
+ * @example
+ * ```tsx
+ * function PokemonSearch() {
+ *   const { query, setQuery, results, isSearching } = useDebouncedSearch<Pokemon>(
+ *     { baseURL: "https://frappe.example.com" },
+ *     "Pokemon",
+ *     { fields: ["name", "pokemon_name"], wait: 250 },
+ *   );
+ *   return (
+ *     <div>
+ *       <input value={query} onChange={e => setQuery(e.target.value)} />
+ *       {isSearching && <span>Searching...</span>}
+ *       {results.map(p => <div key={p.name}>{p.pokemon_name}</div>)}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useDebouncedSearch<TDoc extends FrappeDocData>(config: FrappeConnectionConfig | undefined, doctype: string, options?: DebouncedSearchOptions<TDoc>): DebouncedSearchResult<TDoc>;
+/**
+ * Options for `useThrottledPagination`.
+ */
+export interface ThrottledPaginationOptions {
+    /** Number of items per page (default 20) */
+    pageSize?: number;
+    /** Throttle interval in milliseconds for loadMore (default 200) */
+    throttleMs?: number;
+}
+/**
+ * Return type of `useThrottledPagination`.
+ */
+export interface ThrottledPaginationResult<TDoc extends FrappeDocData> {
+    /** Currently visible items (paginated view of the collection) */
+    items: TDoc[];
+    /** Load the next page of items (throttled) */
+    loadMore: () => void;
+    /** Whether more items are available beyond the current page */
+    hasMore: boolean;
+    /** Whether the collection is still loading */
+    isLoading: boolean;
+}
+/**
+ * Throttled pagination hook for TanStack DB collections.
+ *
+ * Provides a paginated window over a TanStack DB collection backed by Frappe.
+ * The `loadMore` callback is throttled using TanStack Pacer to prevent
+ * rapid-fire scroll events from over-fetching.
+ *
+ * @typeParam TDoc - The Frappe document type
+ * @param collection - A TanStack DB Collection, or undefined
+ * @param options - Pagination options (pageSize, throttleMs)
+ * @returns `{ items, loadMore, hasMore, isLoading }`
+ *
+ * @example
+ * ```tsx
+ * function PokemonList() {
+ *   const collection = useFrappeCollection<Pokemon>(config, "Pokemon");
+ *   const { items, loadMore, hasMore, isLoading } = useThrottledPagination(
+ *     collection,
+ *     { pageSize: 10, throttleMs: 200 },
+ *   );
+ *
+ *   return (
+ *     <div onScroll={handleScroll}>
+ *       {items.map(p => <div key={p.name}>{p.pokemon_name}</div>)}
+ *       {hasMore && <button onClick={loadMore}>Load More</button>}
+ *       {isLoading && <span>Loading...</span>}
+ *     </div>
+ *   );
+ * }
+ * ```
+ */
+export declare function useThrottledPagination<TDoc extends FrappeDocData>(collection: Collection<TDoc, string> | undefined, options?: ThrottledPaginationOptions): ThrottledPaginationResult<TDoc>;
+/**
+ * Options for `createRateLimitedBatch`.
+ */
+export interface RateLimitedBatchOptions {
+    /** The Frappe doctype */
+    doctype: string;
+    /** The mutation operation to perform (create | update | delete) */
+    operation: "create" | "update" | "delete";
+    /** Maximum operations per second (default 5) */
+    maxPerSecond?: number;
+    /** Number of items to send per batch request (default 10) */
+    batchSize?: number;
+    /** SyncModule instance for sending mutations */
+    syncModule: SyncModule;
+}
+/**
+ * Return type of `createRateLimitedBatch`.
+ */
+export interface RateLimitedBatchHandle<TDoc extends FrappeDocData> {
+    /** Add an item to the batch queue */
+    add: (name: string, data?: Partial<TDoc>) => void;
+    /** Execute all queued items with rate limiting */
+    execute: (callbacks?: {
+        onProgress?: (completed: number, total: number) => void;
+    }) => Promise<void>;
+}
+/**
+ * Creates a rate-limited batch processor for bulk Frappe operations.
+ *
+ * Uses TanStack Pacer's `AsyncRateLimiter` to enforce per-second rate
+ * limits when executing bulk create/update/delete operations against
+ * a Frappe backend via SyncModule.
+ *
+ * @typeParam TDoc - The Frappe document type
+ * @param options - Batch configuration (doctype, operation, rate limits, syncModule)
+ * @returns `{ add(name, data), execute({ onProgress }) }`
+ *
+ * @example
+ * ```typescript
+ * const batch = createRateLimitedBatch<Pokemon>({
+ *   doctype: "Pokemon",
+ *   operation: "update",
+ *   maxPerSecond: 5,
+ *   batchSize: 10,
+ *   syncModule,
+ * });
+ *
+ * for (const pokemon of allPokemon) {
+ *   batch.add(pokemon.name, { hp: 100 });
+ * }
+ *
+ * await batch.execute({
+ *   onProgress: (done, total) => console.log(`${done}/${total}`),
+ * });
+ * ```
+ */
+export declare function createRateLimitedBatch<TDoc extends FrappeDocData>(options: RateLimitedBatchOptions): RateLimitedBatchHandle<TDoc>;
+//# sourceMappingURL=pacer.d.ts.map

package/types/pacer.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"pacer.d.ts","sourceRoot":"","sources":["../src/pacer.ts"],"names":[],"mappings":"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"}

package/types/plugin/index.d.ts

@@ -0,0 +1,11 @@
+interface LanguageServiceProxy {
+    getExternalFiles(): string[];
+    getSourceFile(fileName: string, languageVersion: any, _onError?: any, _shouldCreateNewSourceFile?: boolean, _length?: number): any;
+}
+declare function init(modules: {
+    typescript: any;
+}): {
+    create: (info: any) => LanguageServiceProxy;
+};
+export default init;
+//# sourceMappingURL=index.d.ts.map

package/types/plugin/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/plugin/index.ts"],"names":[],"mappings":"AAaA,UAAU,oBAAoB;IAC5B,gBAAgB,IAAI,MAAM,EAAE,CAAC;IAC7B,aAAa,CACX,QAAQ,EAAE,MAAM,EAChB,eAAe,EAAE,GAAG,EACpB,QAAQ,CAAC,EAAE,GAAG,EACd,0BAA0B,CAAC,EAAE,OAAO,EACpC,OAAO,CAAC,EAAE,MAAM,GACf,GAAG,CAAC;CACR;AAED,iBAAS,IAAI,CAAC,OAAO,EAAE;IAAE,UAAU,EAAE,GAAG,CAAA;CAAE;mBAOlB,GAAG,KAAG,oBAAoB;EA0GjD;AAGD,eAAe,IAAI,CAAC"}