@plasmicapp/data-sources 0.1.202 → 0.1.203

package/dist/index.d.ts

@@ -82,8 +82,9 @@ export declare function executePlasmicDataOp<T extends SingleRowResult | ManyRow
 /**
  * Executes a server query, returning either the result of the query or a
  * PlasmicUndefinedServerProxy if the query depends on data that is not yet ready
+ * @deprecated
  */
-export declare function executeServerQuery<F extends (...args: any[]) => any>(serverQuery: ServerQuery<F>): Promise<ServerQueryResult<ReturnType<F> | {}>>;
+export declare function executeServerQuery<F extends (...args: any[]) => any>(query: PlasmicQuery<F>): Promise<ServerQueryResult<ReturnType<F>>>;
 
 export declare function Fetcher(props: FetcherProps): React_2.ReactElement | null;
 
@@ -100,6 +101,7 @@ export declare function makeCacheKey(dataOp: DataOp, opts?: {
     userAuthToken?: string | null;
 }): string;
 
+/** Make a cache key for a query */
 export declare function makeQueryCacheKey(id: string, params: any[]): string;
 
 export declare interface ManyRowsResult<T = any> {
@@ -109,10 +111,8 @@ export declare interface ManyRowsResult<T = any> {
     paginate?: Pagination;
 }
 
-export declare function mkPlasmicUndefinedServerProxy(): {
-    data: {};
-    isLoading: boolean;
-};
+/** @deprecated */
+export declare function mkPlasmicUndefinedServerProxy<T>(): ServerQueryResult<T>;
 
 export declare function normalizeData(rawData: unknown): NormalizedData | undefined;
 
@@ -126,6 +126,31 @@ export declare interface Pagination {
     pageIndex: number;
 }
 
+export declare interface PlasmicQuery<F extends (...args: unknown[]) => Promise<unknown> = (...args: unknown[]) => Promise<unknown>> {
+    fn: F;
+    execParams: () => Parameters<F>;
+    id: string;
+}
+
+export declare interface PlasmicQueryResult<T = unknown> {
+    /**
+     * Returns the key if params have resolved.
+     */
+    key: string | null;
+    /**
+     * Returns the data if the query resolved.
+     * Throws the error if the query rejected.
+     * Throws PlasmicUndefinedDataErrorPromise if the query params are not ready.
+     */
+    data: T;
+    isLoading: boolean;
+}
+
+declare interface PlasmicUndefinedDataErrorPromise extends Promise<any> {
+    plasmicType: "PlasmicUndefinedDataError";
+    message: string;
+}
+
 export declare type QueryResult = Partial<ManyRowsResult<any>> & {
     error?: any;
     isLoading?: boolean;
@@ -133,12 +158,7 @@ export declare type QueryResult = Partial<ManyRowsResult<any>> & {
 
 declare type ResolvableDataOp = DataOp | undefined | null | (() => DataOp | undefined | null);
 
-export declare interface ServerQuery<F extends (...args: any[]) => Promise<any>> {
-    fn: F;
-    execParams: () => Parameters<F>;
-    id: string;
-}
-
+/** @deprecated */
 export declare interface ServerQueryResult<T = any> {
     data: T;
     isLoading: boolean;
@@ -167,6 +187,111 @@ export declare interface TableSchema {
     fields: TableFieldSchema[];
 }
 
+/**
+ * Creates a $queries variable that can be used before queries are completed.
+ *
+ * Each query gets a StatefulQueryResult which implements PlasmicQueryResult.
+ * If data is attempted to be accessed before query completion,
+ * PlasmicUndefinedDataErrorPromise is thrown. Dependent queries can catch this
+ * and delay its own execution until the dependent data is ready.
+ *
+ * When a query execution completes, the StatefulQueryResult must be notified
+ * via resolvePromise or rejectPromise.
+ */
+export declare function unstable_createDollarQueries<QueryName extends string>(queryNames: QueryName[]): Record<QueryName, PlasmicQueryResult>;
+
+/**
+ * Executes all queries and returns the query data keyed by cache key.
+ *
+ * Example codegen:
+ *
+ * export function create$Queries() {
+ *   return createDollarQueries(["result", "dep"]);
+ * }
+ * type QueryName = keyof ReturnType<typeof create$Queries>;
+ * export function createQueries(
+ *   $ctx: Record<string, any>,
+ *   $queries: Record<QueryName, PlasmicQueryResult>,
+ * ) {
+ *   return {
+ *     result: {
+ *       id: "plus",
+ *       fn: (a, b) => a + b,
+ *       execParams: () => [1, $queries.dep.data],
+ *     },
+ *     dep: {
+ *       id: "times",
+ *       fn: (a, b) => a * b,
+ *       execParams: () => [2, 3],
+ *     },
+ *   }
+ * }
+ *
+ * export async function ServerComponent() {
+ *   const $ctx = useDataEnv();
+ *   const $queries = createDollarQueries();
+ *   const queries = createQueries($ctx, $queries);
+ *   const prefetchedCache = await executePlasmicQueries($queries, queries);
+ *   return (
+ *     <PlasmicQueryDataProvider prefetchedCache={prefetchedCache}>
+ *       <ClientComponent />
+ *     </PlasmicQueryDataProvider>
+ *   );
+ * }
+ */
+export declare function unstable_executePlasmicQueries<QueryName extends string>($queries: Record<QueryName, PlasmicQueryResult>, queries: Record<QueryName, PlasmicQuery>): Promise<{
+    [cacheKey: string]: unknown;
+}>;
+
+/**
+ * This hook's job is to execute queries and re-render when query state changes.
+ * Data caching can be controlled via @plasmicapp/query.
+ *
+ * The actual results will be available in $queries generated by
+ * createDollarQueries.
+ *
+ * Prefetched query data can be passed to
+ * <PlasmicQueryDataProvider prefetchedCache={...}>.
+ *
+ * Example codegen:
+ *
+ * export function create$Queries() {
+ *   return createDollarQueries(["result", "dep"]);
+ * }
+ * type QueryName = keyof ReturnType<typeof create$Queries>;
+ * export function createQueries(
+ *   $ctx: Record<string, any>,
+ *   $queries: Record<QueryName, PlasmicQueryResult>,
+ * ) {
+ *   return {
+ *     result: {
+ *       id: "plus",
+ *       fn: (a, b) => a + b,
+ *       execParams: () => [1, $queries.dep.data],
+ *     },
+ *     dep: {
+ *       id: "times",
+ *       fn: (a, b) => a * b,
+ *       execParams: () => [2, 3],
+ *     },
+ *   }
+ * }
+ *
+ * export function ClientComponent() {
+ *   const $queries = React.useMemo(create$Queries, []);
+ *   const queries = React.useMemo(() => createQueries($queries), [$queries]);
+ *   usePlasmicQueries($queries, queries);
+ *   return <div>{$queries.result.data}</div> // $queries.result.data may suspend
+ * }
+ */
+export declare function unstable_usePlasmicQueries<QueryName extends string>($queries: Record<QueryName, PlasmicQueryResult>, queries: Record<QueryName, PlasmicQuery>): void;
+
+/**
+ * Wraps each PlasmicQueryResult so that they return a hardcoded string for
+ * undefined/loading and error cases.
+ */
+export declare function unstable_wrapDollarQueriesForMetadata<T extends Record<string, PlasmicQueryResult>>($queries: T, ifUndefined?: (promise: PlasmicUndefinedDataErrorPromise) => unknown, ifError?: (err: unknown) => unknown): T;
+
 /**
  * @deprecated Prefer using `usePlasmicDataOp` directly instead.
  */
@@ -188,8 +313,19 @@ export declare function usePlasmicDataOp<T extends SingleRowResult | ManyRowsRes
  */
 export declare function usePlasmicInvalidate(): (invalidatedKeys: string[] | null | undefined) => Promise<any[] | undefined>;
 
-export declare function usePlasmicServerQuery<F extends (...args: any[]) => Promise<any>>(serverQuery: ServerQuery<F>, fallbackData?: ReturnType<F>, opts?: {
+/**
+ * @deprecated
+ * This export will be deleted before RSC release.
+ * TODO: Rename to usePlasmicQuery
+ * TODO: Reference $query directly.
+ * TODO: Use paramsResult from usePlasmicQueries
+ */
+export declare function usePlasmicServerQuery<T, F extends (...args: any[]) => Promise<T>>(query: PlasmicQuery<F>, fallbackData?: T, opts?: {
     noUndefinedDataProxy?: boolean;
-}): Partial<ServerQueryResult<ReturnType<F>>>;
+    settledCount?: number;
+    onStarted?: (key: string, promise: Promise<T>) => void;
+    onResolved?: (key: string, data: T) => void;
+    onRejected?: (key: string | null, error: unknown) => void;
+}): Partial<PlasmicQueryResult<T>>;
 
 export { }