@plasmicapp/data-sources 1.0.0 → 1.0.1

package/dist/index.d.ts

@@ -1,7 +1,6 @@
 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 */
@@ -44,6 +43,12 @@ 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;
@@ -81,6 +86,13 @@ declare interface ExecuteOpts {
 /** @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;
 
@@ -153,18 +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;
@@ -256,106 +326,41 @@ export declare interface TableSchema {
 }
 
 /**
- * @internal
- * 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.
+ * Executes all queries from a serialized component tree and returns query results.
  *
- * When a query execution completes, the StatefulQueryResult must be notified
- * via resolvePromise or rejectPromise.
+ * 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_createDollarQueries<QueryName extends string>(queryNames: QueryName[]): Record<QueryName, PlasmicQueryResult>;
-
-/**
- * @internal
- * 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;
-}>;
+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
@@ -381,13 +386,4 @@ export declare function usePlasmicDataOp<T extends SingleRowResult | ManyRowsRes
 /** @deprecated See https://docs.plasmic.app/learn/integrations */
 export declare function usePlasmicInvalidate(): (invalidatedKeys: string[] | null | undefined) => Promise<any[] | undefined>;
 
-/**
- * @deprecated
- * This export will be deleted before RSC release.
- * TODO: Rename to usePlasmicQuery
- * TODO: Reference $query directly.
- * 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 { }

package/dist/index.esm.js

@@ -387,16 +387,29 @@ var StatefulQueryResult = class {
   }
 };
 function safeExec(tryData, ifUndefined, ifError) {
+  const result = safeExecResult(tryData);
+  if ("promise" in result) {
+    return ifUndefined(result.promise);
+  } else if ("error" in result) {
+    return ifError(result.error);
+  } else {
+    return result.data;
+  }
+}
+function safeExecResult(tryData) {
   try {
-    return tryData();
+    return { data: tryData() };
   } catch (err) {
     if (isPlasmicUndefinedDataErrorPromise(err)) {
-      return ifUndefined(err);
+      return { promise: err };
     } else {
-      return ifError(err);
+      return { error: err };
     }
   }
 }
+function assertUnexpectedNodeType(x) {
+  throw new Error(`Unexpected node type: ${x}`);
+}
 function resolveParams(params) {
   return safeExec(
     () => ({
@@ -477,6 +490,19 @@ var SyncPromise = class {
     );
   }
 };
+function shallowEqualRecords(a, b) {
+  if (Object.is(a, b)) {
+    return true;
+  }
+  const aKeys = Object.keys(a);
+  const bKeys = Object.keys(b);
+  if (aKeys.length !== bKeys.length) {
+    return false;
+  }
+  return aKeys.every(
+    (key) => Object.prototype.hasOwnProperty.call(b, key) && Object.is(a[key], b[key])
+  );
+}
 var SettablePromise = class {
   constructor() {
     this.promise = new Promise((resolve, reject) => {
@@ -572,7 +598,31 @@ function sortObjectsDeep(value, visitedObjects) {
 
 // src/serverQueries/client.ts
 var GLOBAL_CACHE = /* @__PURE__ */ new Map();
-function usePlasmicQueries($queries, queries) {
+function usePlasmicQueries(tree, $props, $ctx, $state) {
+  const stableProps = useShallowStableRecord($props);
+  const stableCtx = useShallowStableRecord($ctx);
+  const $stateRef = React3.useRef($state != null ? $state : {});
+  $stateRef.current = $state != null ? $state : {};
+  const $queries = React3.useMemo(
+    () => createDollarQueries(Object.keys(tree.queries)),
+    [tree]
+  );
+  const queries = React3.useMemo(() => {
+    return mapRecords(
+      (_name, q) => ({
+        id: q.id,
+        fn: q.fn,
+        execParams: () => q.args({
+          $q: $queries,
+          $props: stableProps,
+          $ctx: stableCtx,
+          $state: $stateRef.current,
+          $scopedItemVars: {}
+        })
+      }),
+      tree.queries
+    );
+  }, [$queries, stableCtx, stableProps, tree]);
   const wrappedQueries = React3.useMemo(() => wrapQueries(queries), [queries]);
   const $queryStates = $queries;
   const { fallback: prefetchedCache, cache: swrCache } = usePlasmicDataConfig2();
@@ -639,13 +689,14 @@ function usePlasmicQueries($queries, queries) {
     },
     [wrappedQueries, $queryStates, settledCount]
   );
-  return mapRecords(
+  mapRecords(
     (_queryName, $query, query) => {
-      return usePlasmicQuery($query, query, settledCount);
+      usePlasmicQuery($query, query, settledCount);
     },
     $queryStates,
     wrappedQueries
   );
+  return $queries;
 }
 function wrapQueries(queries) {
   return mapRecords((_queryName, query) => {
@@ -770,24 +821,261 @@ function usePlasmicQuery($query, query, settledCount) {
   }
   return result;
 }
+function useShallowStableRecord(value) {
+  const ref = React3.useRef(value);
+  if (!shallowEqualRecords(ref.current, value)) {
+    ref.current = value;
+  }
+  return ref.current;
+}
 
 // src/serverQueries/server.ts
-function executePlasmicQueries($queries, queries) {
-  return __async(this, null, function* () {
-    const doneQueryResults = yield Promise.all(
-      mapRecordEntries(
-        (_queryName, $query, query) => {
-          return executePlasmicQuery($query, query);
-        },
-        $queries,
-        queries
-      )
+var ROOT_COMPONENT_KEY_PATH = "root";
+function appendKeyPath(currentKeyPath, currentInput) {
+  return currentKeyPath ? `${currentKeyPath}/${currentInput}` : currentInput;
+}
+function executeQueryTree(rootNode, options, queriesByComponent) {
+  const { $props, $ctx } = options;
+  const initialContext = {
+    $props,
+    $ctx,
+    $state: {},
+    $q: {},
+    $scopedItemVars: {}
+  };
+  return executeComponentNode(rootNode, {
+    context: initialContext,
+    parentKeyPath: "",
+    childIndex: 0,
+    queriesByComponent
+  });
+}
+function executeNode(node, params) {
+  const p = { node, params, type: node.type };
+  switch (p.type) {
+    case "component":
+      return executeComponentNode(p.node, p.params);
+    case "codeComponent":
+      return executeCodeComponentNode(p.node, p.params);
+    case "dataProvider":
+      return executeDataProviderNode(p.node, p.params);
+    case "visibility":
+      return executeVisibilityNode(p.node, p.params);
+    case "repeated":
+      return executeRepeatedNode(p.node, p.params);
+    default:
+      assertUnexpectedNodeType(p);
+  }
+}
+function executeComponentNode(node, params) {
+  const {
+    context: parentContext,
+    parentKeyPath,
+    childIndex,
+    queriesByComponent
+  } = params;
+  const isRoot = parentKeyPath === "";
+  let componentKeyPath;
+  let evaluatedProps;
+  if (isRoot) {
+    componentKeyPath = ROOT_COMPONENT_KEY_PATH;
+    evaluatedProps = parentContext.$props;
+  } else {
+    componentKeyPath = appendKeyPath(parentKeyPath, `c${childIndex}`);
+    evaluatedProps = {};
+    for (const [propName, propFn] of Object.entries(node.propsContext)) {
+      const result = safeExecResult(() => propFn(parentContext));
+      if (!("data" in result)) {
+        return [];
+      }
+      evaluatedProps[propName] = result.data;
+    }
+  }
+  let componentQueries = queriesByComponent.get(componentKeyPath);
+  if (!componentQueries) {
+    componentQueries = {};
+    queriesByComponent.set(componentKeyPath, componentQueries);
+  }
+  const componentContext = {
+    $props: evaluatedProps,
+    $ctx: parentContext.$ctx,
+    $state: parentContext.$state,
+    $q: componentQueries,
+    $scopedItemVars: parentContext.$scopedItemVars
+  };
+  const discovered = [];
+  for (const [queryName, query] of Object.entries(node.queries)) {
+    if (componentQueries[queryName]) {
+      continue;
+    }
+    const $query = new StatefulQueryResult();
+    componentQueries[queryName] = $query;
+    const capturedContext = componentContext;
+    const capturedArgsFn = query.args;
+    const plasmicQuery = {
+      id: query.id,
+      fn: query.fn,
+      execParams: () => capturedArgsFn(capturedContext)
+    };
+    discovered.push({ $query, query: plasmicQuery });
+  }
+  node.children.forEach((child, idx) => {
+    discovered.push(
+      ...executeNode(child, {
+        context: componentContext,
+        parentKeyPath: componentKeyPath,
+        childIndex: idx,
+        queriesByComponent
+      })
     );
-    return Object.fromEntries(
-      Object.values(doneQueryResults).map(($query) => [$query.key, $query.data])
+  });
+  return discovered;
+}
+function executeCodeComponentNode(node, params) {
+  if (node.serverRenderingConfig === false) {
+    return [];
+  }
+  const { context, parentKeyPath, childIndex, queriesByComponent } = params;
+  const nodeKeyPath = appendKeyPath(parentKeyPath, `cc${childIndex}`);
+  const evaluatedProps = {};
+  for (const [propName, propFn] of Object.entries(node.propsContext)) {
+    const result = safeExecResult(() => propFn(context));
+    if ("data" in result) {
+      evaluatedProps[propName] = result.data;
+    } else {
+      return [];
+    }
+  }
+  const childContext = {
+    $props: evaluatedProps,
+    $ctx: context.$ctx,
+    $state: context.$state,
+    $q: context.$q,
+    $scopedItemVars: context.$scopedItemVars
+  };
+  return node.children.flatMap(
+    (child, idx) => executeNode(child, {
+      context: childContext,
+      parentKeyPath: nodeKeyPath,
+      childIndex: idx,
+      queriesByComponent
+    })
+  );
+}
+function executeDataProviderNode(node, params) {
+  const { context, parentKeyPath, childIndex, queriesByComponent } = params;
+  const nodeKeyPath = appendKeyPath(parentKeyPath, `dp${childIndex}`);
+  const dataResult = safeExecResult(() => node.data(context));
+  if (!("data" in dataResult)) {
+    return [];
+  }
+  const childContext = {
+    $props: context.$props,
+    $ctx: __spreadProps(__spreadValues({}, context.$ctx), {
+      [node.name]: dataResult.data
+    }),
+    $state: context.$state,
+    $q: context.$q,
+    $scopedItemVars: context.$scopedItemVars
+  };
+  return node.children.flatMap(
+    (child, idx) => executeNode(child, {
+      context: childContext,
+      parentKeyPath: nodeKeyPath,
+      childIndex: idx,
+      queriesByComponent
+    })
+  );
+}
+function executeVisibilityNode(node, params) {
+  const { context, parentKeyPath, childIndex, queriesByComponent } = params;
+  const nodeKeyPath = appendKeyPath(parentKeyPath, `v${childIndex}`);
+  const visibilityResult = safeExecResult(() => node.visibilityExpr(context));
+  if (!("data" in visibilityResult) || !visibilityResult.data) {
+    return [];
+  }
+  return node.children.flatMap(
+    (child, idx) => executeNode(child, {
+      context,
+      parentKeyPath: nodeKeyPath,
+      childIndex: idx,
+      queriesByComponent
+    })
+  );
+}
+function executeRepeatedNode(node, params) {
+  const { context, parentKeyPath, childIndex, queriesByComponent } = params;
+  const nodeKeyPath = appendKeyPath(parentKeyPath, `r${childIndex}`);
+  const collectionResult = safeExecResult(() => node.collectionExpr(context));
+  if (!("data" in collectionResult) || !Array.isArray(collectionResult.data)) {
+    return [];
+  }
+  return collectionResult.data.flatMap((item, index) => {
+    const itemContext = {
+      $props: context.$props,
+      $ctx: context.$ctx,
+      $state: context.$state,
+      $q: context.$q,
+      $scopedItemVars: __spreadProps(__spreadValues({}, context.$scopedItemVars), {
+        [node.itemName]: item,
+        [node.indexName]: index
+      })
+    };
+    const itemKeyPath = appendKeyPath(nodeKeyPath, `i${index}`);
+    return node.children.flatMap(
+      (child, idx) => executeNode(child, {
+        context: itemContext,
+        parentKeyPath: itemKeyPath,
+        childIndex: idx,
+        queriesByComponent
+      })
     );
   });
 }
+function executePlasmicQueries(rootNode, options) {
+  return __async(this, null, function* () {
+    const queriesByComponent = /* @__PURE__ */ new Map();
+    const discoveredQueries = [];
+    while (true) {
+      const newQueries = executeQueryTree(rootNode, options, queriesByComponent);
+      if (newQueries.length === 0) {
+        break;
+      }
+      discoveredQueries.push(...newQueries);
+      yield Promise.all(
+        newQueries.map(
+          (d) => executePlasmicQuery(d.$query, d.query).catch(() => {
+          })
+        )
+      );
+    }
+    const cache = {};
+    for (const d of discoveredQueries) {
+      if ("data" in d.$query.current) {
+        cache[d.$query.current.key] = d.$query.current.data;
+      }
+    }
+    const queries = {};
+    const rootQueries = queriesByComponent.get(ROOT_COMPONENT_KEY_PATH);
+    if (rootQueries) {
+      for (const [name, $query] of Object.entries(rootQueries)) {
+        if ("data" in $query.current) {
+          queries[name] = {
+            key: $query.key,
+            data: $query.current.data,
+            isLoading: false
+          };
+        }
+      }
+    }
+    for (const d of discoveredQueries) {
+      if ("error" in d.$query.current) {
+        throw d.$query.current.error;
+      }
+    }
+    return { cache, queries };
+  });
+}
 function executePlasmicQuery($query, query) {
   return __async(this, null, function* () {
     if ($query.current.state === "loading" || $query.current.state === "done") {
@@ -1214,7 +1502,6 @@ export {
   makeCacheKey,
   makeQueryCacheKey,
   normalizeData,
-  createDollarQueries as unstable_createDollarQueries,
   executePlasmicQueries as unstable_executePlasmicQueries,
   usePlasmicQueries as unstable_usePlasmicQueries,
   wrapDollarQueriesForMetadata as unstable_wrapDollarQueriesForMetadata,