@wasp.sh/wasp-cli-darwin-x64-unknown 0.25.0 → 0.26.0

package/data/Generator/templates/sdk/wasp/client/operations/hooks.ts

@@ -1,347 +0,0 @@
-import {
-  QueryClient,
-  QueryKey,
-  useMutation,
-  UseMutationOptions,
-  useQueryClient,
-  useQuery as rqUseQuery,
-  UseQueryResult,
-} from "@tanstack/react-query";
-import { Action, Query } from "./rpc";
-import { makeQueryCacheKey } from "./queries/core";
-export { configureQueryClient } from "./queryClient";
-
-// PUBLIC API
-export function useQuery<Input, Output>(
-  query: Query<Input, Output>,
-  queryFnArgs?: Input,
-  options?: any
-): UseQueryResult<Output, Error> {
-  if (typeof query !== 'function') {
-    throw new TypeError('useQuery requires queryFn to be a function.')
-  }
-
-  if (!query.queryCacheKey) {
-    throw new TypeError('queryFn needs to have queryCacheKey property defined.')
-  }
-
-  return rqUseQuery({
-    // todo: The full queryCacheKey is constructed in two places, both here and
-    // inside the Query. See https://github.com/wasp-lang/wasp/issues/2017
-    // FIXME: query fns don't handle the `undefined` case correctly
-    // https://github.com/wasp-lang/wasp/issues/2017
-    queryKey: makeQueryCacheKey(query, (queryFnArgs as Input)),
-    // FIXME: query fns don't handle the `undefined` case correctly
-    // https://github.com/wasp-lang/wasp/issues/2017
-    queryFn: () => query(queryFnArgs as Input),
-    ...options,
-  })
-}
-
-// PUBLIC API
-/**
- * A hook for adding extra behavior to a Wasp Action (e.g., optimistic updates).
- *
- * @param actionFn The Wasp Action you wish to enhance/decorate.
- * @param actionOptions An options object for enhancing/decorating the given Action.
- * @returns A decorated Action with added behavior but an unchanged API.
- */
-export function useAction<Input = unknown, Output = unknown>(
-  actionFn: Action<Input, Output>,
-  actionOptions?: ActionOptions<Input>
-): typeof actionFn {
-  const queryClient = useQueryClient();
-
-  let mutationFn = actionFn;
-  let options = {};
-  if (actionOptions?.optimisticUpdates) {
-    const optimisticUpdatesDefinitions = actionOptions.optimisticUpdates.map(
-      translateToInternalDefinition
-    );
-    mutationFn = makeOptimisticUpdateMutationFn(
-      actionFn,
-      optimisticUpdatesDefinitions
-    );
-    options = makeRqOptimisticUpdateOptions(
-      queryClient,
-      optimisticUpdatesDefinitions
-    );
-  }
-
-  // NOTE: We decided to hide React Query's extra mutation features (e.g.,
-  // isLoading, onSuccess and onError callbacks, synchronous mutate) and only
-  // expose a simple async function whose API matches the original Action.
-  // We did this to avoid cluttering the API with stuff we're not sure we need
-  // yet (e.g., isLoading), to postpone the action vs mutation dilemma, and to
-  // clearly separate our opinionated API from React Query's lower-level
-  // advanced API (which users can also use)
-  const mutation = useMutation(mutationFn, options);
-
-  // This assertion is necessary because, when the Input is void, we want to
-  // present the function as not accepting a payload (which isn't consistent
-  // with how it's defined).
-  return ((args: Input) => mutation.mutateAsync(args)) as typeof actionFn;
-}
-
-// PUBLIC API
-// todo: Improve this type. Details here:
-// https://github.com/wasp-lang/wasp/issues/2017 
-/**
- * A documented (public) way to define optimistic updates.
- */
-export type OptimisticUpdateDefinition<ActionInput, CachedData> = {
-  getQuerySpecifier: GetQuerySpecifier<ActionInput, CachedData>;
-  updateQuery: UpdateQuery<ActionInput, CachedData>;
-};
-
-/**
- * An options object passed into the `useAction` hook and used to enhance the
- * action with extra options.
- *
- */
-type ActionOptions<ActionInput> = {
-  optimisticUpdates: OptimisticUpdateDefinition<ActionInput, any>[];
-};
-
-/**
- * A function that takes an item and returns a Wasp Query specifier.
- */
-type GetQuerySpecifier<ActionInput, CachedData> = (
-  item: ActionInput
-) => QuerySpecifier<unknown, CachedData>;
-
-// todo: Improve the type's signature for when the cache is empty. Details here:
-// https://github.com/wasp-lang/wasp/issues/2017
-/**
- * A function that takes an item and the previous state of the cache, and returns
- * the desired (new) state of the cache.
- */
-type UpdateQuery<ActionInput, CachedData> = (
-  item: ActionInput,
-  oldData: CachedData | undefined
-) => CachedData;
-
-// todo: Improve this type signature. Details here:
-// https://github.com/wasp-lang/wasp/issues/2017
-/**
- * A public query specifier used for addressing Wasp queries. See our docs for details:
- * https://wasp.sh/docs/language/features#the-useaction-hook.
- */
-type QuerySpecifier<Input, Output> = [Query<Input, Output>, ...any[]];
-
-/**
- * An internal (undocumented, private, desugared) way of defining optimistic updates.
- */
-type InternalOptimisticUpdateDefinition<ActionInput, CachedData> = {
-  getQueryKey: (item: ActionInput) => QueryKey;
-  updateQuery: UpdateQuery<ActionInput, CachedData>;
-};
-
-/**
- * An UpdateQuery function "instantiated" with a specific item. It only takes
- * the current state of the cache and returns the desired (new) state of the
- * cache.
- */
-type SpecificUpdateQuery<CachedData> = (oldData: CachedData | undefined) => CachedData;
-
-/**
- * A specific, "instantiated" optimistic update definition which contains a
- * fully-constructed query key and a specific update function.
- */
-type SpecificOptimisticUpdateDefinition<Item> = {
-  queryKey: QueryKey;
-  updateQuery: SpecificUpdateQuery<Item>;
-};
-
-type InternalAction<Input, Output> = Action<Input, Output> & {
-  internal<CachedData extends unknown>(
-    item: Input,
-    optimisticUpdateDefinitions: SpecificOptimisticUpdateDefinition<CachedData>[]
-  ): Promise<Output>;
-};
-
-/**
- * Translates/Desugars a public optimistic update definition object into a
- * definition object our system uses internally.
- *
- * @param publicOptimisticUpdateDefinition An optimistic update definition
- * object that's a part of the public API:
- * https://wasp.sh/docs/language/features#the-useaction-hook.
- * @returns An internally-used optimistic update definition object.
- */
-function translateToInternalDefinition<Item, CachedData>(
-  publicOptimisticUpdateDefinition: OptimisticUpdateDefinition<Item, CachedData>
-): InternalOptimisticUpdateDefinition<Item, CachedData> {
-  const { getQuerySpecifier, updateQuery } = publicOptimisticUpdateDefinition;
-
-  const definitionErrors: string[] = [];
-  if (typeof getQuerySpecifier !== "function") {
-    definitionErrors.push("`getQuerySpecifier` is not a function.");
-  }
-  if (typeof updateQuery !== "function") {
-    definitionErrors.push("`updateQuery` is not a function.");
-  }
-  if (definitionErrors.length) {
-    throw new TypeError(
-      `Invalid optimistic update definition: ${definitionErrors.join(", ")}.`
-    );
-  }
-
-  return {
-    getQueryKey: (item) => getRqQueryKeyFromSpecifier(getQuerySpecifier(item)),
-    updateQuery,
-  };
-}
-
-/**
- * Creates a function that performs an action while telling it about the
- * optimistic updates it caused.
- *
- * @param actionFn The Wasp Action.
- * @param optimisticUpdateDefinitions The optimisitc updates the action causes.
- * @returns An decorated action which performs optimistic updates.
- */
-function makeOptimisticUpdateMutationFn<Input, Output, CachedData>(
-  actionFn: Action<Input, Output>,
-  optimisticUpdateDefinitions: InternalOptimisticUpdateDefinition<
-    Input,
-    CachedData
-  >[]
-): typeof actionFn {
-  return (function performActionWithOptimisticUpdates(item: Input) {
-    const specificOptimisticUpdateDefinitions = optimisticUpdateDefinitions.map(
-      (generalDefinition) =>
-        getOptimisticUpdateDefinitionForSpecificItem(generalDefinition, item)
-    );
-    return (actionFn as InternalAction<Input, Output>).internal(
-      item,
-      specificOptimisticUpdateDefinitions
-    );
-    // This assertion is necessary because, when the Input is void, we want to
-    // present the function as not accepting a payload (which isn't consistent
-    // with how it's defined).
-  }) as typeof actionFn;
-}
-
-/**
- * Given a ReactQuery query client and our internal definition of optimistic
- * updates, this function constructs an object describing those same optimistic
- * updates in a format we can pass into React Query's useMutation hook. In other
- * words, it translates our optimistic updates definition into React Query's
- * optimistic updates definition. Check their docs for details:
- * https://tanstack.com/query/v4/docs/guides/optimistic-updates?from=reactQueryV3&original=https://react-query-v3.tanstack.com/guides/optimistic-updates
- *
- * @param queryClient The QueryClient instance used by React Query.
- * @param optimisticUpdateDefinitions A list containing internal optimistic
- * updates definition objects (i.e., a list where each object carries the
- * instructions for performing particular optimistic update).
- * @returns An object containing 'onMutate' and 'onError' functions
- * corresponding to the given optimistic update definitions (check the docs
- * linked above for details).
- */
-function makeRqOptimisticUpdateOptions<ActionInput, CachedData>(
-  queryClient: QueryClient,
-  optimisticUpdateDefinitions: InternalOptimisticUpdateDefinition<
-    ActionInput,
-    CachedData
-  >[]
-): Pick<UseMutationOptions, "onMutate" | "onError"> {
-  async function onMutate(item) {
-    const specificOptimisticUpdateDefinitions = optimisticUpdateDefinitions.map(
-      (generalDefinition) =>
-        getOptimisticUpdateDefinitionForSpecificItem(generalDefinition, item)
-    );
-
-    // Cancel any outgoing refetches (so they don't overwrite our optimistic update).
-    // Theoretically, we can be a bit faster. Instead of awaiting the
-    // cancellation of all queries, we could cancel and update them in parallel.
-    // However, awaiting cancellation hasn't yet proven to be a performance bottleneck.
-    await Promise.all(
-      specificOptimisticUpdateDefinitions.map(({ queryKey }) =>
-        queryClient.cancelQueries(queryKey)
-      )
-    );
-
-    // We're using a Map to correctly serialize query keys that contain objects.
-    const previousData: Map<QueryKey, CachedData | undefined> = new Map();
-    specificOptimisticUpdateDefinitions.forEach(({ queryKey, updateQuery }) => {
-      // Snapshot the currently cached value.
-      const previousDataForQuery: CachedData | undefined =
-        queryClient.getQueryData(queryKey);
-
-      // Attempt to optimistically update the cache using the new value.
-      try {
-        queryClient.setQueryData(queryKey, updateQuery);
-      } catch (e) {
-        console.error(
-          "The `updateQuery` function threw an exception, skipping optimistic update:"
-        );
-        console.error(e);
-      }
-
-      // Remember the snapshotted value to restore in case of an error.
-      previousData.set(queryKey, previousDataForQuery);
-    });
-
-    return { previousData };
-  }
-
-  function onError(_err, _item, context) {
-    // All we do in case of an error is roll back all optimistic updates. We ensure
-    // not to do anything else because React Query rethrows the error. This allows
-    // the programmer to handle the error as they usually would (i.e., we want the
-    // error handling to work as it would if the programmer wasn't using optimistic
-    // updates).
-    context.previousData.forEach(async (data, queryKey) => {
-      await queryClient.cancelQueries(queryKey);
-      queryClient.setQueryData(queryKey, data);
-    });
-  }
-
-  return {
-    onMutate,
-    onError,
-  };
-}
-
-/**
- * Constructs the definition for optimistically updating a specific item. It
- * uses a closure over the updated item to construct an item-specific query key
- * (e.g., useful when the query key depends on an ID).
- *
- * @param optimisticUpdateDefinition The general, "uninstantiated" optimistic
- * update definition with a function for constructing the query key.
- * @param item The item triggering the Action/optimistic update (i.e., the
- * argument passed to the Action).
- * @returns A specific optimistic update definition which corresponds to the
- * provided definition and closes over the provided item.
- */
-function getOptimisticUpdateDefinitionForSpecificItem<ActionInput, CachedData>(
-  optimisticUpdateDefinition: InternalOptimisticUpdateDefinition<
-    ActionInput,
-    CachedData
-  >,
-  item: ActionInput
-): SpecificOptimisticUpdateDefinition<CachedData> {
-  const { getQueryKey, updateQuery } = optimisticUpdateDefinition;
-  return {
-    queryKey: getQueryKey(item),
-    updateQuery: (old) => updateQuery(item, old),
-  };
-}
-
-// todo: Address the duplication between this function and the one in
-// queries/core.ts. Details here: https://github.com/wasp-lang/wasp/issues/2017
-/**
- * Translates a Wasp query specifier to a query cache key used by React Query.
- *
- * @param querySpecifier A query specifier that's a part of the public API:
- * https://wasp.sh/docs/language/features#the-useaction-hook.
- * @returns A cache key React Query internally uses for addressing queries.
- */
-function getRqQueryKeyFromSpecifier(
-  querySpecifier: QuerySpecifier<unknown, unknown>
-): QueryKey {
-  const [queryFn, ...otherKeys] = querySpecifier;
-  return [...(queryFn as any).queryCacheKey, ...otherKeys];
-}

package/data/Generator/templates/sdk/wasp/client/operations/internal/resources.js

@@ -1,85 +0,0 @@
-import { queryClientInitialized } from '../queryClient.js'
-import { makeUpdateHandlersMap } from './updateHandlersMap'
-import { hashQueryKey } from '@tanstack/react-query'
-
-// Map where key is resource name and value is Set
-// containing query ids of all the queries that use
-// that resource.
-const resourceToQueryCacheKeys = new Map()
-
-const updateHandlers = makeUpdateHandlersMap(hashQueryKey)
-
-// PRIVATE API
-/**
- * Remembers that specified query is using specified resources.
- * If called multiple times for same query, resources are added, not reset.
- * @param {string[]} queryCacheKey - Unique key under used to identify query in the cache.
- * @param {string[]} resources - Names of resources that query is using.
- */
-export function addResourcesUsedByQuery(queryCacheKey, resources) {
-  for (const resource of resources) {
-    let cacheKeys = resourceToQueryCacheKeys.get(resource)
-    if (!cacheKeys) {
-      cacheKeys = new Set()
-      resourceToQueryCacheKeys.set(resource, cacheKeys)
-    }
-    cacheKeys.add(queryCacheKey)
-  }
-}
-
-export function registerActionInProgress(optimisticUpdateTuples) {
-  optimisticUpdateTuples.forEach(
-    ({ queryKey, updateQuery }) => updateHandlers.add(queryKey, updateQuery)
-  )
-}
-
-export async function registerActionDone(resources, optimisticUpdateTuples) {
-  optimisticUpdateTuples.forEach(({ queryKey }) => updateHandlers.remove(queryKey))
-  await invalidateQueriesUsing(resources)
-}
-
-export function getActiveOptimisticUpdates(queryKey) {
-  return updateHandlers.getUpdateHandlers(queryKey)
-}
-
-export async function invalidateAndRemoveQueries() {
-  const queryClient = await queryClientInitialized
-  // If we don't reset the queries before removing them, Wasp will stay on
-  // the same page. The user would have to manually refresh the page to "finish"
-  // logging out.
-  // When a query is removed, the `Observer` is removed as well, and the components
-  // that are using the query are not re-rendered. This is why we need to reset
-  // the queries, so that the `Observer` is re-created and the components are re-rendered.
-  // For more details: https://github.com/wasp-lang/wasp/pull/1014/files#r1111862125
-  queryClient.resetQueries()
-  // If we don't remove the queries after invalidating them, the old query data
-  // remains in the cache, casuing a potential privacy issue.
-  queryClient.removeQueries()
-}
-
-/**
- * Invalidates all queries that are using specified resources.
- * @param {string[]} resources - Names of resources.
- */
-async function invalidateQueriesUsing(resources) {
-  const queryClient = await queryClientInitialized
-
-  const queryCacheKeysToInvalidate = getQueriesUsingResources(resources)
-  await Promise.all(
-    queryCacheKeysToInvalidate.map(
-      queryCacheKey => queryClient.invalidateQueries(queryCacheKey)
-    )
-  )
-}
-
-/**
- * @param {string} resource - Resource name.
- * @returns {string[]} Array of "query cache keys" of queries that use specified resource.
- */
-function getQueriesUsingResource(resource) {
-  return Array.from(resourceToQueryCacheKeys.get(resource) || [])
-}
-
-function getQueriesUsingResources(resources) {
-  return Array.from(new Set(resources.flatMap(getQueriesUsingResource)))
-}

package/data/Generator/templates/sdk/wasp/client/operations/internal/updateHandlersMap.js

@@ -1,37 +0,0 @@
-export function makeUpdateHandlersMap(calculateHash) {
-  const updateHandlers = new Map()
-
-  function getHandlerTuples(queryKeyHash) {
-    return updateHandlers.get(queryKeyHash) || [];
-  }
-
-  function add(queryKey, updateQuery) {
-    const queryKeyHash = calculateHash(queryKey)
-    const handlers = getHandlerTuples(queryKeyHash);
-    updateHandlers.set(queryKeyHash, [...handlers, { queryKey, updateQuery }])
-  }
-
-  function getUpdateHandlers(queryKey) {
-    const queryKeyHash = calculateHash(queryKey)
-    return getHandlerTuples(queryKeyHash).map(({ updateQuery }) => updateQuery)
-  }
-
-  function remove(queryKeyToRemove) {
-    const queryKeyHash = calculateHash(queryKeyToRemove)
-    const filteredHandlers = getHandlerTuples(queryKeyHash).filter(
-      ({ queryKey }) => queryKey !== queryKeyToRemove
-    )
-
-    if (filteredHandlers.length > 0) {
-      updateHandlers.set(queryKeyHash, filteredHandlers)
-    } else {
-      updateHandlers.delete(queryKeyHash)
-    }
-  }
-
-  return {
-    add,
-    remove,
-    getUpdateHandlers,
-  }
-}

package/data/Generator/templates/sdk/wasp/client/operations/queryClient.ts

@@ -1,34 +0,0 @@
-import { QueryClient, QueryClientConfig } from '@tanstack/react-query'
-
-const defaultQueryClientConfig = {};
-
-let queryClientConfig: QueryClientConfig,
-  resolveQueryClientInitialized: (...args: any[]) => any,
-  isQueryClientInitialized: boolean;
-
-// PRIVATE API (framework code)
-export const queryClientInitialized: Promise<QueryClient> = new Promise(
-  (resolve) => {
-    resolveQueryClientInitialized = resolve;
-  }
-);
-
-// PUBLIC API
-export function configureQueryClient(config: QueryClientConfig): void {
-  if (isQueryClientInitialized) {
-    throw new Error(
-      "Attempted to configure the QueryClient after initialization"
-    );
-  }
-
-  queryClientConfig = config;
-}
-
-// PRIVATE API (framework code)
-export function initializeQueryClient(): void {
-  const queryClient = new QueryClient(
-    queryClientConfig ?? defaultQueryClientConfig
-  );
-  isQueryClientInitialized = true;
-  resolveQueryClientInitialized(queryClient);
-}

package/data/Generator/templates/sdk/wasp/client/operations/rpc.ts

@@ -1,96 +0,0 @@
-import { type Route } from "../index.js";
-import type {
-  IfAny,
-  _Awaited,
-  _ReturnType,
-} from "../../universal/types.js"
-
-// PRIVATE API (for SDK, should maybe be public, users define values of this
-// type).
-//
-// Frontend queries are functions with some extra properties (metadata).
-// 
-// To simplify working with the type (i.e., referencing the type's two different
-// components), we've defined it as an intersection of two distinct types:
-// one representing the function (QueryFunction), and the other representing the
-// metadata (QueryMetadata) .
-/**
- * The client Query object type. It's a callable Query function with some extra
- * properties (metadata).
- */
-export type Query<Input, Output> = QueryFunction<Input, Output> & QueryMetadata
-
-// PRIVATE API (for SDK, should maybe be public, users define values of this
-// type)
-/**
- * The client Action object type (unlike a Query, it's just a normal function).
- */
-export type Action<Input, Output> = ClientOperation<Input, Output>
-
-// PRIVATE API (for SDK)
-/**
- * The client Query function type.
- */
-export type QueryFunction<Input, Output> = ClientOperation<Input, Output>
-
-// PRIVATE API (for SDK)
-// todo: revisit what we expose. Also, queryCacheKey is confusing and
-// incorrect.Details here: https://github.com/wasp-lang/wasp/issues/2017
-/**
- *  All extra properties (metadata) found on a Query object type.
- */
-export type QueryMetadata = {
-  queryCacheKey: string[]
-  route: Route
-}
-
-// PRIVATE API (needed in SDK)
-// Explanation:
-// - Custom `_Awaited` and `_ReturnType` - Read the comments above their
-// definitions.
-// - `Parameters<BackendOperation> extends []` - See here:
-// https://github.com/wasp-lang/wasp/pull/1992/files#r1583040080
-/**
- * Constructs the client RPC function type from the type of the operation's
- * definition on the backend.
- */
-export type OperationRpcFor<BackendOperation extends GenericBackendOperation> =
-  Parameters<BackendOperation> extends []
-  ? ClientOperation<void, _Awaited<_ReturnType<BackendOperation>>>
-  : ClientOperation<
-    Parameters<BackendOperation>[0],
-    _Awaited<_ReturnType<BackendOperation>>
-  >
-
-// PRIVATE API (needed in SDK)
-/**
- * A supertype of all possible backend operation definitions (i.e., Queries and
- * Actions) 
- */
-export type GenericBackendOperation = (args: never, context: any) => unknown
-
-// PRIVATE API (needed in SDK)
-/**
- * A supertype of all possible frontend RPC function types.
- */
-export type GenericOperationRpc = (args: never) => Promise<unknown>
-
-// NOTE: There's some duplication in the below types.
-// Read the discussion here to understand why before trying to remove it:
-// https://github.com/wasp-lang/wasp/pull/2170#discussion_r1671285049
-//
-// Read this to understand the type: https://github.com/wasp-lang/wasp/pull/2170#issue-2398830273
-type ClientOperation<Input, Output> =
-  IfAny<
-    Input,
-    (args?: any) => Promise<Output>,
-    ClientOperationWithNonAnyInput<Input, Output>
-  >
-
-// Read this to understand the type: https://github.com/wasp-lang/wasp/pull/1090#discussion_r1159732471
-type ClientOperationWithNonAnyInput<Input, Output> =
-  [Input] extends [never]
-  ? (args?: unknown) => Promise<Output>
-  : [Input] extends [void]
-  ? () => Promise<Output>
-  : (args: Input) => Promise<Output>

package/data/Generator/templates/sdk/wasp/client/router/linkHelpers.ts

@@ -1,48 +0,0 @@
-import type { Params, Search } from "./types";
-
-// PRIVATE API
-export function interpolatePath(
-  path: string,
-  params?: Params,
-  search?: Search,
-  hash?: string
-) {
-  const interpolatedPath = params ? interpolatePathParams(path, params) : path
-  const interpolatedSearch = search
-    ? `?${new URLSearchParams(search).toString()}`
-    : ''
-  const interpolatedHash = hash ? `#${hash}` : ''
-  return interpolatedPath + interpolatedSearch + interpolatedHash
-}
-
-function interpolatePathParams(path: string, params: Params) {
-  function mapPathPart(part: string) {
-    if (part === '*') {
-      return params['*'];
-    }
-    if (part.startsWith(":")) {
-      const paramName = extractParamNameFromPathPart(part);
-      return params[paramName];
-    }
-    return part;
-  }
-
-  const interpolatedPath = path
-    .split("/")
-    .map(mapPathPart)
-    .filter(isValidPathPart)
-    .join("/");
-    
-  return path.startsWith("/") ? `/${interpolatedPath}` : interpolatedPath;
-}
-
-function isValidPathPart(part: any): boolean {
-  return !!part;
-}
-
-function extractParamNameFromPathPart(paramString: string) {
-  if (paramString.endsWith("?")) {
-    return paramString.slice(1, -1);
-  }
-  return paramString.slice(1);
-}