syncorejs 0.2.1 → 0.2.3

package/dist/_vendor/svelte/index.d.ts

@@ -1,43 +1,269 @@
 import { Readable } from "svelte/store";
-import { FunctionArgs, FunctionReference, FunctionResult, SyncoreClient } from "../core/index.d.mts";
+import { FunctionArgs, FunctionReference, FunctionResult, PaginationOptions, PaginationResult, SyncoreClient, SyncoreQueryState, SyncoreRuntimeStatus, UsePaginatedQueryResult } from "../core/index.d.mts";
 
 //#region src/index.d.ts
 type OptionalArgsTuple<TArgs> = Record<never, never> extends TArgs ? [args?: TArgs] : [args: TArgs];
+type QueryRequestInput<TReference extends FunctionReference<"query"> = FunctionReference<"query">> = Record<never, never> extends FunctionArgs<TReference> ? {
+  query: TReference;
+  args?: FunctionArgs<TReference> | Skip;
+} : {
+  query: TReference;
+  args: FunctionArgs<TReference> | Skip;
+};
+type QueriesRequestInput = Record<string, QueryRequestInput>;
+type QueryStateForEntry<TEntry> = TEntry extends QueryRequestInput<infer TReference> ? SyncoreQueryState<FunctionResult<TReference>> : never;
+type CreateQueriesStoreResult<TEntries extends QueriesRequestInput> = { [TKey in keyof TEntries]: QueryStateForEntry<TEntries[TKey]> };
+type PaginatedQueryReference = FunctionReference<"query", Record<string, unknown>, PaginationResult<unknown>>;
+type PaginatedQueryArgs<TReference extends FunctionReference<"query">> = FunctionArgs<TReference> extends {
+  paginationOpts: PaginationOptions;
+} ? Omit<FunctionArgs<TReference>, "paginationOpts"> : never;
+type PaginatedQueryItem<TReference extends FunctionReference<"query">> = FunctionResult<TReference> extends PaginationResult<infer TItem> ? TItem : never;
 /**
- * The observable state exposed by a Syncore-backed Svelte query store.
+ * The reactive query state shape emitted by Syncore's Svelte store factories.
+ *
+ * Extends {@link SyncoreQueryState} with the same fields (`data`, `error`,
+ * `status`, `runtimeStatus`, `isLoading`, `isError`, `isReady`). Returned as
+ * the value of stores created by {@link createQueryStore} and
+ * {@link createClientQueryStore}.
  */
-interface SyncoreQueryStoreState<TResult> {
-  /** The latest local result for the watched query. */
-  data: TResult | undefined;
-  /** The latest local error for the watched query, if any. */
-  error: Error | undefined;
-  /** The current watch lifecycle status. */
-  status: "loading" | "ready" | "error";
-}
+interface SyncoreQueryStoreState<TResult> extends SyncoreQueryState<TResult> {}
 /**
- * Store a Syncore client in the current Svelte component context.
+ * A sentinel value that tells Syncore store factories to skip the query.
+ *
+ * Use `skip` in place of a query’s `args` argument to avoid firing the query
+ * while some required data is not yet available (e.g. a user ID that loads
+ * asynchronously). The store will remain in a `"loading"` / skipped state
+ * until a non-skip value is provided.
+ *
+ * ```svelte
+ * <script>
+ *   import { createQueryValueStore, skip } from "syncorejs/svelte";
+ *   import { api } from "../syncore/_generated/api";
+ *
+ *   export let userId: string | undefined;
+ *
+ *   $: profile = createQueryValueStore(
+ *     api.users.get,
+ *     userId ? { id: userId } : skip
+ *   );
+ * </script>
+ * ```
+ */
+declare const skip: "skip";
+type Skip = typeof skip;
+/**
+ * Store the Syncore client in Svelte’s component context.
+ *
+ * Call this once at the root of your component tree (e.g. in a layout or
+ * root `+layout.svelte`) so that the context-aware store factories
+ * (`createQueryStore`, `createQueriesStore`, etc.) can retrieve it
+ * automatically without prop-drilling.
+ *
+ * ```svelte
+ * <!-- +layout.svelte -->
+ * <script>
+ *   import { setSyncoreClient } from "syncorejs/svelte";
+ *   export let data; // { client } from +layout.ts
+ *   setSyncoreClient(data.client);
+ * </script>
+ * <slot />
+ * ```
+ *
+ * @param client - The ready Syncore client to store in context.
+ * @returns The same `client` for convenience.
  */
 declare function setSyncoreClient(client: SyncoreClient): SyncoreClient;
 /**
- * Read the active Syncore client from the current Svelte component context.
+ * Retrieve the Syncore client from Svelte’s component context.
+ *
+ * Throws if {@link setSyncoreClient} has not been called by an ancestor
+ * component. Only use this inside Svelte components; for standalone scripts
+ * keep an explicit reference to the client instead.
+ *
+ * @throws `Error` when no client is found in the component context.
  */
 declare function getSyncoreClient(): SyncoreClient;
 /**
- * Create a readable Svelte store backed by a reactive Syncore query.
+ * Create a reactive Svelte store that tracks the Syncore runtime status.
+ *
+ * Uses the client from Svelte context (set via {@link setSyncoreClient}).
+ * Subscribe to gate your UI on `"ready"` before rendering data-dependent
+ * components.
+ *
+ * ```svelte
+ * <script>
+ *   import { createSyncoreStatusStore } from "syncorejs/svelte";
+ *   const status = createSyncoreStatusStore();
+ * </script>
+ *
+ * {#if $status.kind === "ready"}
+ *   <App />
+ * {:else}
+ *   <Loading />
+ * {/if}
+ * ```
+ */
+declare function createSyncoreStatusStore(): Readable<SyncoreRuntimeStatus>;
+/**
+ * Create a reactive Svelte store that tracks the Syncore runtime status.
+ *
+ * Accepts an explicit `client` rather than reading from Svelte context,
+ * making it usable outside component trees (e.g. in module-level code or
+ * SvelteKit `load` functions).
+ *
+ * @param client - The Syncore client to observe.
+ */
+declare function createClientSyncoreStatusStore(client: SyncoreClient): Readable<SyncoreRuntimeStatus>;
+/**
+ * Create a reactive Svelte store that emits the current value of a Syncore
+ * query, or `undefined` while loading.
+ *
+ * Uses the client from Svelte context (set via {@link setSyncoreClient}).
+ * Pass `skip` as `args` to pause the query.
+ *
+ * ```svelte
+ * <script>
+ *   import { createQueryValueStore } from "syncorejs/svelte";
+ *   import { api } from "../syncore/_generated/api";
+ *
+ *   const todos = createQueryValueStore(api.todos.list);
+ * </script>
+ *
+ * {#each $todos ?? [] as todo}
+ *   <p>{todo.text}</p>
+ * {/each}
+ * ```
+ */
+declare function createQueryValueStore<TReference extends FunctionReference<"query">>(reference: TReference, ...args: OptionalArgsTuple<FunctionArgs<TReference>> | [Skip]): Readable<FunctionResult<TReference> | undefined>;
+/**
+ * Create a reactive Svelte store that emits the current value of a Syncore
+ * query, or `undefined` while loading.
+ *
+ * Accepts an explicit `client` instead of reading from Svelte context.
+ *
+ * @param client - The Syncore client to query against.
+ */
+declare function createClientQueryValueStore<TReference extends FunctionReference<"query">>(client: SyncoreClient, reference: TReference, ...args: OptionalArgsTuple<FunctionArgs<TReference>> | [Skip]): Readable<FunctionResult<TReference> | undefined>;
+/**
+ * Create a reactive Svelte store that emits the full {@link SyncoreQueryState}
+ * for a query, including `data`, `error`, `status`, and `isPending`.
+ *
+ * Uses the client from Svelte context (set via {@link setSyncoreClient}).
+ *
+ * ```svelte
+ * <script>
+ *   import { createQueryStore } from "syncorejs/svelte";
+ *   import { api } from "../syncore/_generated/api";
+ *
+ *   const state = createQueryStore(api.todos.list);
+ * </script>
+ *
+ * {#if $state.isPending}
+ *   <Spinner />
+ * {:else if $state.error}
+ *   <Error message={$state.error.message} />
+ * {:else}
+ *   {#each $state.data as todo}<p>{todo.text}</p>{/each}
+ * {/if}
+ * ```
+ */
+declare function createQueryStore<TReference extends FunctionReference<"query">>(reference: TReference, ...args: OptionalArgsTuple<FunctionArgs<TReference>> | [Skip]): Readable<SyncoreQueryStoreState<FunctionResult<TReference>>>;
+/**
+ * Create a reactive Svelte store that emits the full {@link SyncoreQueryState}
+ * for a query, including `data`, `error`, `status`, and `isPending`.
+ *
+ * Accepts an explicit `client` instead of reading from Svelte context.
+ *
+ * @param client - The Syncore client to query against.
+ */
+declare function createClientQueryStore<TReference extends FunctionReference<"query">>(client: SyncoreClient, reference: TReference, ...args: OptionalArgsTuple<FunctionArgs<TReference>> | [Skip]): Readable<SyncoreQueryStoreState<FunctionResult<TReference>>>;
+/**
+ * Create a reactive Svelte store that simultaneously observes multiple
+ * Syncore queries.
+ *
+ * Uses the client from Svelte context (set via {@link setSyncoreClient}).
+ * Each key in `entries` corresponds to a key in the emitted result object.
+ *
+ * ```svelte
+ * <script>
+ *   import { createQueriesStore } from "syncorejs/svelte";
+ *   import { api } from "../syncore/_generated/api";
+ *
+ *   const stores = createQueriesStore({
+ *     todos: { query: api.todos.list },
+ *     user: { query: api.users.me },
+ *   });
+ * </script>
+ *
+ * <p>{$stores.user.data?.name} has {$stores.todos.data?.length} todos</p>
+ * ```
+ */
+declare function createQueriesStore<TEntries extends QueriesRequestInput>(entries: TEntries): Readable<CreateQueriesStoreResult<TEntries>>;
+/**
+ * Create a reactive Svelte store that simultaneously observes multiple
+ * Syncore queries.
+ *
+ * Accepts an explicit `client` instead of reading from Svelte context.
+ *
+ * @param client - The Syncore client to query against.
+ */
+declare function createClientQueriesStore<TEntries extends QueriesRequestInput>(client: SyncoreClient, entries: TEntries): Readable<CreateQueriesStoreResult<TEntries>>;
+/**
+ * Create a reactive Svelte store for cursor-based paginated Syncore queries.
+ *
+ * Uses the client from Svelte context (set via {@link setSyncoreClient}).
+ * The store handles page tracking and exposes a `loadMore()` function so you
+ * can implement “Load More” UIs without manual cursor management.
+ *
+ * The query referenced by `reference` must accept a `paginationOpts`
+ * argument and return a {@link PaginationResult}.
+ *
+ * ```svelte
+ * <script>
+ *   import { createPaginatedQueryStore } from "syncorejs/svelte";
+ *   import { api } from "../syncore/_generated/api";
+ *
+ *   const result = createPaginatedQueryStore(
+ *     api.todos.listPaginated,
+ *     {},
+ *     { initialNumItems: 10 }
+ *   );
+ * </script>
+ *
+ * {#each $result.results as todo}<p>{todo.text}</p>{/each}
+ * {#if $result.canLoadMore}
+ *   <button on:click={() => $result.loadMore(10)}>Load more</button>
+ * {/if}
+ * ```
+ *
+ * @param reference - A paginated query function reference.
+ * @param args - Query arguments excluding `paginationOpts`, or `skip`.
+ * @param options.initialNumItems - Number of items to fetch on the first page.
  */
-declare function createQueryStore<TReference extends FunctionReference<"query">>(reference: TReference, ...args: OptionalArgsTuple<FunctionArgs<TReference>>): Readable<SyncoreQueryStoreState<FunctionResult<TReference>>>;
+declare function createPaginatedQueryStore<TReference extends PaginatedQueryReference>(reference: TReference, args: PaginatedQueryArgs<TReference> | Skip, options: {
+  initialNumItems: number;
+}): Readable<UsePaginatedQueryResult<PaginatedQueryItem<TReference>>>;
 /**
- * Create a readable Svelte store backed by a reactive Syncore query.
+ * Create a reactive Svelte store for cursor-based paginated Syncore queries.
+ *
+ * Accepts an explicit `client` instead of reading from Svelte context.
+ *
+ * @param client - The Syncore client to query against.
+ * @param reference - A paginated query function reference.
+ * @param args - Query arguments excluding `paginationOpts`, or `skip`.
+ * @param options.initialNumItems - Number of items to fetch on the first page.
  */
-declare function createClientQueryStore<TReference extends FunctionReference<"query">>(client: SyncoreClient, reference: TReference, ...args: OptionalArgsTuple<FunctionArgs<TReference>>): Readable<SyncoreQueryStoreState<FunctionResult<TReference>>>;
+declare function createClientPaginatedQueryStore<TReference extends PaginatedQueryReference>(client: SyncoreClient, reference: TReference, args: PaginatedQueryArgs<TReference> | Skip, options: {
+  initialNumItems: number;
+}): Readable<UsePaginatedQueryResult<PaginatedQueryItem<TReference>>>;
 /**
- * Create a function that executes a Syncore mutation.
+ * Creates a callable wrapper for a Syncore mutation using the contextual client.
  */
 declare function createMutation<TReference extends FunctionReference<"mutation">>(reference: TReference): (...args: OptionalArgsTuple<FunctionArgs<TReference>>) => Promise<FunctionResult<TReference>>;
 /**
- * Create a function that executes a Syncore action.
+ * Creates a callable wrapper for a Syncore action using the contextual client.
  */
 declare function createAction<TReference extends FunctionReference<"action">>(reference: TReference): (...args: OptionalArgsTuple<FunctionArgs<TReference>>) => Promise<FunctionResult<TReference>>;
 //#endregion
-export { OptionalArgsTuple, SyncoreQueryStoreState, createAction, createClientQueryStore, createMutation, createQueryStore, getSyncoreClient, setSyncoreClient };
+export { CreateQueriesStoreResult, OptionalArgsTuple, SyncoreQueryStoreState, createAction, createClientPaginatedQueryStore, createClientQueriesStore, createClientQueryStore, createClientQueryValueStore, createClientSyncoreStatusStore, createMutation, createPaginatedQueryStore, createQueriesStore, createQueryStore, createQueryValueStore, createSyncoreStatusStore, getSyncoreClient, setSyncoreClient, skip };
 //# sourceMappingURL=index.d.ts.map

package/dist/_vendor/svelte/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":";;;;KAUY,iBAAA,UACV,MAAA,uBAA6B,KAAA,IAAS,IAAA,GAAO,KAAA,KAAU,IAAA,EAAM,KAAA;;AAD/D;;UAMiB,sBAAA;EALf;EAOA,IAAA,EAAM,OAAA;EAPuC;EAU7C,KAAA,EAAO,KAAA;EAV2D;EAalE,MAAA;AAAA;;;;iBAQc,gBAAA,CAAiB,MAAA,EAAQ,aAAA,GAAgB,aAAA;;;;iBAQzC,gBAAA,CAAA,GAAoB,aAAA;AAxBpC;;;AAAA,iBAqCgB,gBAAA,oBAAoC,iBAAA,UAAA,CAClD,SAAA,EAAW,UAAA,KACR,IAAA,EAAM,iBAAA,CAAkB,YAAA,CAAa,UAAA,KACvC,QAAA,CAAS,sBAAA,CAAuB,cAAA,CAAe,UAAA;;;;iBAOlC,sBAAA,oBACK,iBAAA,UAAA,CAEnB,MAAA,EAAQ,aAAA,EACR,SAAA,EAAW,UAAA,KACR,IAAA,EAAM,iBAAA,CAAkB,YAAA,CAAa,UAAA,KACvC,QAAA,CAAS,sBAAA,CAAuB,cAAA,CAAe,UAAA;;;;iBAelC,cAAA,oBACK,iBAAA,aAAA,CAEnB,SAAA,EAAW,UAAA,OAER,IAAA,EAAM,iBAAA,CAAkB,YAAA,CAAa,UAAA,OACrC,OAAA,CAAQ,cAAA,CAAe,UAAA;AA1D5B;;;AAAA,iBAqEgB,YAAA,oBAAgC,iBAAA,WAAA,CAC9C,SAAA,EAAW,UAAA,OAER,IAAA,EAAM,iBAAA,CAAkB,YAAA,CAAa,UAAA,OACrC,OAAA,CAAQ,cAAA,CAAe,UAAA"}
+{"version":3,"file":"index.d.ts","names":[],"sources":["../src/index.ts"],"mappings":"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"}