@multiplatform.one/frappe 6.0.0

package/src/index.ts

@@ -0,0 +1,215 @@
+/**
+ * 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.
+ */
+
+// Core Frappe functionality
+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";
+
+// TanStack DB collection integration
+export {
+  createFrappeCollection,
+  frappeCollectionOptions,
+  createFixtureCollection,
+  fixtureCollectionOptions,
+} from "./collection";
+export type { FrappeCollectionOptionsConfig, FixtureCollectionOptionsConfig } from "./collection";
+export { createOptimisticAction } from "./optimistic";
+
+// React hooks for Frappe + TanStack DB
+export {
+  useFrappeCollection,
+  useInfiniteScroll,
+  useFrappeInfiniteList,
+  __getActiveSyncModule,
+} from "./frappeReact";
+export type {
+  UseFrappeCollectionConfig,
+  UseInfiniteScrollConfig,
+  UseInfiniteScrollResult,
+  UseFrappeInfiniteListConfig,
+  UseFrappeInfiniteListResult,
+} from "./frappeReact";
+
+// TanStack Pacer utilities for Frappe
+export { useDebouncedSearch, useThrottledPagination, createRateLimitedBatch } from "./pacer";
+export type {
+  DebouncedSearchOptions,
+  DebouncedSearchResult,
+  FrappeConnectionConfig,
+  ThrottledPaginationOptions,
+  ThrottledPaginationResult,
+  RateLimitedBatchOptions,
+  RateLimitedBatchHandle,
+} from "./pacer";
+
+// Re-export TanStack DB React hooks
+export { useLiveQuery } from "@tanstack/react-db";
+export { createCollection, createTransaction } from "@tanstack/db";
+
+// Re-export TanStack DB query builder functions
+export {
+  eq,
+  gt,
+  gte,
+  lt,
+  lte,
+  and,
+  or,
+  not,
+  inArray,
+  like,
+  ilike,
+  isUndefined,
+  isNull,
+  count,
+  avg,
+  sum,
+  min,
+  max,
+} from "@tanstack/db";
+
+// Re-export TanStack Pacer primitives
+export {
+  Debouncer,
+  AsyncDebouncer,
+  Throttler,
+  AsyncThrottler,
+  RateLimiter,
+  AsyncRateLimiter,
+  Queuer,
+  AsyncQueuer,
+  Batcher,
+  AsyncBatcher,
+  debounce,
+  asyncDebounce,
+  throttle,
+  asyncThrottle,
+  rateLimit,
+  asyncRateLimit,
+  queue,
+  asyncQueue,
+  batch,
+  asyncBatch,
+} from "@tanstack/pacer";
+
+// Fixture support for testing
+export * from "./fixtures";
+
+// Core infrastructure exports (for advanced users)
+export {
+  HttpClient,
+  getCookie,
+  setCookie,
+  deleteCookie,
+  setSSRCookies,
+  clearSSRCookies,
+  invalidateCookieCache,
+} from "./core/http";
+export type {
+  AuthConfig,
+  FrappeError,
+  ListOptions,
+  CustomEndpoints,
+  FrappeLiveConfig,
+} from "./core/types";
+
+// frappe_live extension types
+export type {
+  BackfillArgs,
+  BackfillResponse,
+  CursorPaginationArgs,
+  CursorPaginationResponse,
+  BatchMutationType,
+  BatchMutation,
+  BatchMutationsArgs,
+  BatchMutationResult,
+  BatchMutationsResponse,
+  ListSinceArgs,
+  ListSinceResponse,
+} from "./db";
+
+// DocType metadata hooks
+export {
+  useDocTypeMeta,
+  useLinkSearch,
+  useDocTypeSearch,
+  parseDependsOn,
+  parseFormLayout,
+} from "./doctype";
+export type {
+  DocTypeMeta,
+  DocTypeField,
+  DocTypePermission,
+  FormSection,
+  FormColumn,
+  FrappeFieldType,
+  LinkSearchResult,
+  LinkSearchOptions,
+  DocTypeSearchResult,
+} from "./doctype";
+
+// Common types
+export type { FrappeDocValue, FrappeDocData, FrappeDoc, ChildTableRow } from "./common/types";
+
+// Sync types with advanced features
+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";
+
+// Filter utilities
+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";
+
+// Tree DocType support
+export { TreeDbModule } from "./db";
+export type {
+  GetTreeChildrenArgs,
+  GetTreeAncestorsArgs,
+  GetTreeDescendantsArgs,
+  TreeNode,
+} from "./db";
+
+// TypeScript Language Service Plugin
+export { default as frappePlugin } from "./plugin";

package/src/optimistic.spec.ts

@@ -0,0 +1,13 @@
+import { createOptimisticAction as tanstackCreateOptimisticAction } from "@tanstack/db";
+import { describe, expect, it } from "vitest";
+import { createOptimisticAction } from "./optimistic";
+
+describe("createOptimisticAction re-export", () => {
+  it("is the same reference as @tanstack/db createOptimisticAction", () => {
+    expect(createOptimisticAction).toBe(tanstackCreateOptimisticAction);
+  });
+
+  it("is a function", () => {
+    expect(typeof createOptimisticAction).toBe("function");
+  });
+});

package/src/optimistic.ts

@@ -0,0 +1,39 @@
+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;
+ * ```
+ */