@plasmicapp/data-sources 0.1.209 → 1.0.1

package/dist/index.d.ts

@@ -1,9 +1,9 @@
 import { CodeComponentMeta } from '@plasmicapp/host/registerComponent';
 import { PlasmicDataSourceContextValue } from '@plasmicapp/data-sources-context';
 import { default as React_2 } from 'react';
-import { SWRResponse } from '@plasmicapp/query';
 import { usePlasmicDataConfig } from '@plasmicapp/query';
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare type BaseFieldConfig = {
     key?: string;
     fieldId?: string;
@@ -11,6 +11,7 @@ export declare type BaseFieldConfig = {
 
 /**
  * Represents the result of a client-side query.
+ * @deprecated See https://docs.plasmic.app/learn/integrations
  */
 export declare interface ClientQueryResult<T = any> {
     /**
@@ -42,6 +43,13 @@ export declare interface ClientQueryResult<T = any> {
     isLoading?: boolean;
 }
 
+/**
+ * A function that takes the execution context and returns a value.
+ * Used for all dynamic expressions in the query tree (args, collectionExpr, visibilityExpr, data, propsContext values).
+ */
+declare type ContextFn<R> = (ctx: QueryExecutionContext) => R;
+
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare interface DataOp {
     sourceId: string;
     opId: string;
@@ -51,22 +59,19 @@ export declare interface DataOp {
     roleId?: string | null;
 }
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 declare interface DataOpConfig {
     name?: string;
     pageIndex?: number;
     pageSize?: number;
 }
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare interface DataSourceSchema {
     tables: TableSchema[];
 }
 
-declare interface DependencyAwareQueryConfig extends DataOpConfig {
-    $queries: Record<string, any>;
-    setDollarQueries: ($queries: Record<string, any>) => void;
-    getDataOp: () => DataOp;
-}
-
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare function deriveFieldConfigs<T extends BaseFieldConfig>(specifiedFieldsPartial: Partial<T>[], schema: TableSchema | undefined, makeDefaultConfig: (field: TableFieldSchema | undefined) => T): {
     mergedFields: T[];
     minimalFullLengthFields: Partial<T>[];
@@ -78,26 +83,39 @@ declare interface ExecuteOpts {
     paginate?: Pagination;
 }
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare function executePlasmicDataOp<T extends SingleRowResult | ManyRowsResult>(op: DataOp, opts?: ExecuteOpts): Promise<T>;
 
+declare interface ExecutePlasmicQueriesResult {
+    /** All queries, including nested, by query cache key hash. Passed to PlasmicRootProvider */
+    cache: Record<string, unknown>;
+    /** Root component query results keyed by query name. */
+    queries: Record<string, PlasmicQueryResult>;
+}
+
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare function Fetcher(props: FetcherProps): React_2.ReactElement | null;
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare const FetcherMeta: CodeComponentMeta<FetcherProps>;
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare interface FetcherProps extends DataOpConfig {
     dataOp?: DataOp;
     children?: ($queries: Record<string, any>) => React_2.ReactElement | null;
     queries?: Record<string, any>;
 }
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare function makeCacheKey(dataOp: DataOp, opts?: {
     paginate?: Pagination;
     userAuthToken?: string | null;
 }): string;
 
-/** Make a cache key for a query */
+/** @internal Make a cache key for a query */
 export declare function makeQueryCacheKey(id: string, params: any[]): string;
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare interface ManyRowsResult<T = any> {
     data: T[];
     total?: number;
@@ -105,24 +123,29 @@ export declare interface ManyRowsResult<T = any> {
     paginate?: Pagination;
 }
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare function normalizeData(rawData: unknown): NormalizedData | undefined;
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare interface NormalizedData {
     data: Record<string, unknown>[];
     schema?: TableSchema;
 }
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare interface Pagination {
     pageSize: number;
     pageIndex: number;
 }
 
+/** @internal */
 export declare interface PlasmicQuery<F extends (...args: unknown[]) => Promise<unknown> = (...args: unknown[]) => Promise<unknown>> {
     fn: F;
     execParams: () => Parameters<F>;
     id: string;
 }
 
+/** @internal */
 export declare interface PlasmicQueryResult<T = unknown> {
     /**
      * Returns the key if params have resolved.
@@ -142,17 +165,76 @@ declare interface PlasmicUndefinedDataErrorPromise extends Promise<any> {
     message: string;
 }
 
+/** @internal */
+declare interface QueryCodeComponentNode {
+    type: "codeComponent";
+    propsContext: Record<string, ContextFn<unknown>>;
+    serverRenderingConfig?: SerializedServerRenderingConfig;
+    children: QueryNode[];
+}
+
+/** @internal */
+export declare interface QueryComponentNode {
+    type: "component";
+    queries: Record<string, SerializedServerQuery>;
+    propsContext: Record<string, ContextFn<unknown>>;
+    children: QueryNode[];
+}
+
+/** @internal */
+declare interface QueryDataProviderNode {
+    type: "dataProvider";
+    name: string;
+    data: ContextFn<unknown>;
+    children: QueryNode[];
+}
+
+declare interface QueryExecutionContext {
+    $props: Record<string, unknown>;
+    $ctx: Record<string, unknown>;
+    $state: Record<string, unknown>;
+    $q: Record<string, PlasmicQueryResult>;
+    $scopedItemVars: Record<string, unknown>;
+}
+
+/** @internal */
+declare type QueryExecutionInitialContext = Pick<QueryExecutionContext, "$props" | "$ctx">;
+
+/** @internal */
+declare type QueryNode = QueryComponentNode | QueryCodeComponentNode | QueryRepeatedNode | QueryDataProviderNode | QueryVisibilityNode;
+
+/** @internal */
+declare interface QueryRepeatedNode {
+    type: "repeated";
+    collectionExpr: ContextFn<unknown>;
+    itemName: string;
+    indexName: string;
+    children: QueryNode[];
+}
+
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare type QueryResult = Partial<ManyRowsResult<any>> & {
     error?: any;
     isLoading?: boolean;
 };
 
+/** @internal */
+declare interface QueryVisibilityNode {
+    type: "visibility";
+    visibilityExpr: ContextFn<unknown>;
+    children: QueryNode[];
+}
+
 declare type ResolvableDataOp = DataOp | undefined | null | (() => DataOp | undefined | null);
 
-/**
- * Wraps a Promise so that it can be easily resolved/rejected
- * outside the executor param of the Promise constructor.
- */
+declare interface SerializedServerQuery {
+    id: string;
+    fn: (...args: unknown[]) => Promise<unknown>;
+    args: ContextFn<unknown[]>;
+}
+
+declare type SerializedServerRenderingConfig = boolean;
+
 declare class SettablePromise<T> {
     readonly promise: Promise<T>;
     private _resolve;
@@ -162,6 +244,7 @@ declare class SettablePromise<T> {
     reject(error: unknown): void;
 }
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare interface SingleRowResult<T = any> {
     data: T;
     schema: TableSchema;
@@ -221,6 +304,7 @@ export declare type _StatefulQueryState<T = unknown> = {
 /** @internal */
 export declare type _StateListener<T = unknown> = (state: _StatefulQueryState<T>, prevState: _StatefulQueryState<T>) => void;
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare interface TableFieldSchema {
     id: string;
     label?: string;
@@ -230,8 +314,10 @@ export declare interface TableFieldSchema {
     options?: string[];
 }
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare type TableFieldType = "string" | "boolean" | "number" | "date" | "datetime" | "enum" | "json" | "unknown";
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare interface TableSchema {
     id: string;
     schema?: string;
@@ -240,134 +326,64 @@ export declare interface TableSchema {
 }
 
 /**
- * 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:
+ * Executes all queries from a serialized component tree and returns query results.
  *
- * 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>
- *   );
- * }
+ * 1. Walk the tree to discover queries, creating StatefulQueryResult + PlasmicQuery
+ * 2. Execute all newly discovered queries in parallel
+ * 3. After all settle, re-walk. Discover queries from newly expanded repeated nodes
+ * Continue until no new queries found.
  */
-export declare function unstable_executePlasmicQueries<QueryName extends string>($queries: Record<QueryName, PlasmicQueryResult>, queries: Record<QueryName, PlasmicQuery>): Promise<{
-    [cacheKey: string]: unknown;
-}>;
+export declare function unstable_executePlasmicQueries(rootNode: QueryComponentNode, options: QueryExecutionInitialContext): Promise<ExecutePlasmicQueriesResult>;
 
 /**
+ * @internal
  * 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.
+ * The actual results will be available in the returned $queries object.
  *
  * 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 const serverQueryTree = {
+ *   type: "component",
+ *   queries: {
+ *     films: { fn: $$.fetch, id: "fetch", args: ({ $q, $props, $ctx }) => [...] }
+ *   },
+ *   propsContext: {},
+ * };
  *
- * 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 function ClientComponent($props, $ctx) {
+ *   const $q = usePlasmicQueries(serverQueryTree, $props, $ctx);
+ *   return <div>{$q.films.data}</div>
  * }
  */
-export declare function unstable_usePlasmicQueries<QueryName extends string>($queries: Record<QueryName, PlasmicQueryResult>, queries: Record<QueryName, PlasmicQuery>): Record<QueryName, ReturnType<typeof usePlasmicQuery>>;
+export declare function unstable_usePlasmicQueries(tree: QueryComponentNode, $props: Record<string, unknown>, $ctx: Record<string, unknown>, $state?: Record<string, unknown>): Record<string, PlasmicQueryResult>;
 
 /**
+ * @internal
  * 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.
- */
-export declare function useDependencyAwareQuery({ $queries, getDataOp, setDollarQueries, name, pageIndex, pageSize, }: DependencyAwareQueryConfig): void;
-
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare function useNormalizedData(rawData: unknown): NormalizedData | undefined;
 
 export { usePlasmicDataConfig }
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare function usePlasmicDataMutationOp<T extends SingleRowResult | ManyRowsResult>(dataOp: ResolvableDataOp): () => Promise<T | undefined>;
 
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare function usePlasmicDataOp<T extends SingleRowResult | ManyRowsResult, E = any>(dataOp: ResolvableDataOp, opts?: {
     paginate?: Pagination;
     noUndefinedDataProxy?: boolean;
 }): ClientQueryResult<T["data"]>;
 
-/**
- * Returns a function that can be used to invalidate Plasmic query groups.
- */
+/** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare function usePlasmicInvalidate(): (invalidatedKeys: string[] | null | undefined) => Promise<any[] | undefined>;
 
-/**
- * TODO: Use paramsResult from usePlasmicQueries
- */
-declare function usePlasmicQuery<T, F extends (...args: any[]) => Promise<T>>($query: PlasmicQueryResult<T>, query: PlasmicQuery<F>, settledCount?: number): SWRResponse<T, unknown>;
-
 export { }