@wasp.sh/wasp-cli-darwin-x64-unknown 0.20.0

package/data/Generator/templates/sdk/wasp/client/operations/queries/core.ts

@@ -0,0 +1,91 @@
+import { Route } from 'wasp/client'
+import type { _Awaited, _ReturnType } from 'wasp/universal/types'
+import type {
+  GenericBackendOperation,
+  GenericOperationRpc,
+  OperationRpcFor,
+  Query,
+  QueryMetadata,
+} from '../rpc.js'
+import { callOperation, makeOperationRoute } from '../internal/index.js'
+import {
+  addResourcesUsedByQuery,
+  getActiveOptimisticUpdates,
+} from '../internal/resources'
+
+// PRIVATE API (used in the SDK)
+// todo: find ways to remove this duplication and make the type more precise.
+// Details here: https://github.com/wasp-lang/wasp/issues/2017
+export function makeQueryCacheKey<Input, Output>(
+  query: Query<Input, Output>,
+  payload: Input
+): (string | Input)[] {
+  return payload !== undefined ?
+    [...query.queryCacheKey, payload]
+    : query.queryCacheKey
+}
+
+// PRIVATE API (unsed in SDK)
+export function createQuery<BackendQuery extends GenericBackendOperation>(
+  relativeQueryPath: string,
+  entitiesUsed: string[]
+): QueryFor<BackendQuery> {
+  const queryRoute = makeOperationRoute(relativeQueryPath)
+  const queryCacheKey = [relativeQueryPath]
+
+  const queryFn = (async (queryArgs) => {
+    const serverResult = await callOperation(queryRoute, queryArgs)
+    // todo: The full queryCacheKey is constructed in two places, both here and
+    // inside the useQuery hook. See
+    // https://github.com/wasp-lang/wasp/issues/2017
+    const queryCacheKey = makeQueryCacheKey(queryFn as QueryFor<BackendQuery>, queryArgs)
+    return getActiveOptimisticUpdates(queryCacheKey).reduce(
+      (result, update) => update(result),
+      serverResult,
+    )
+    // 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 QueryFunctionFor<BackendQuery>
+
+  return buildAndRegisterQuery(
+    queryFn,
+    { queryCacheKey, queryRoute, entitiesUsed },
+  )
+}
+
+// PRIVATE API (used in SDK)
+export function buildAndRegisterQuery<QF extends GenericOperationRpc>(
+  queryFn: QF,
+  { queryCacheKey, queryRoute, entitiesUsed }:
+    { queryCacheKey: string[], queryRoute: Route, entitiesUsed: string[] }
+): QueryForFunction<QF> {
+  const query = queryFn as QueryForFunction<QF>
+
+  query.queryCacheKey = queryCacheKey
+  query.route = queryRoute
+  addResourcesUsedByQuery(query.queryCacheKey, entitiesUsed)
+
+  return query
+}
+
+// PRIVATE API (but should maybe be public, users define values of this type)
+/**
+ * Constructs the client Query object type from the type of the Query's definition
+ * on the backend.
+ */
+export type QueryFor<BackendQuery extends GenericBackendOperation> =
+  QueryForFunction<QueryFunctionFor<BackendQuery>>
+
+/**
+ * Constructs the client Query function type from the type of the Query's
+ * definition on the backend.
+ */
+type QueryFunctionFor<BackendQuery extends GenericBackendOperation> =
+  OperationRpcFor<BackendQuery>
+
+/**
+ * Returns the appropriate client Query object type for the provided client
+ * Query function type.
+ */
+type QueryForFunction<QF extends GenericOperationRpc> = QF & QueryMetadata

package/data/Generator/templates/sdk/wasp/client/operations/queries/index.ts

@@ -0,0 +1,16 @@
+{{={= =}=}}
+import { type QueryFor, createQuery } from './core'
+{=# queries =}
+{=& operationTypeImportStmt =}
+{=/ queries =}
+{=# queries =}
+
+// PUBLIC API
+export const {= operationName =}: QueryFor<{= operationTypeName =}> = createQuery<{= operationTypeName =}>(
+  '{= queryRoute =}',
+  {=& entitiesArray =},
+)
+{=/ queries =}
+
+// PRIVATE API (used in SDK)
+export { buildAndRegisterQuery } from './core'

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

@@ -0,0 +1,34 @@
+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

@@ -0,0 +1,96 @@
+import { type Route } from "wasp/client";
+import type {
+  IfAny,
+  _Awaited,
+  _ReturnType,
+} from "wasp/universal/types"
+
+// 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/Link.tsx

@@ -0,0 +1,21 @@
+import { useMemo } from 'react'
+import { Link as RouterLink } from 'react-router-dom'
+import { interpolatePath } from './linkHelpers'
+import { type Routes } from './index'
+
+type RouterLinkProps = Parameters<typeof RouterLink>[0]
+
+// PUBLIC API
+export function Link(
+  { to, params, search, hash, ...restOfProps }: Omit<RouterLinkProps, "to">
+  & {
+    search?: Record<string, string>;
+    hash?: string;
+  }
+  & Routes
+): React.JSX.Element {
+  const toPropWithParams = useMemo(() => {
+    return interpolatePath(to, params, search, hash)
+  }, [to, params])
+  return <RouterLink to={toPropWithParams} {...restOfProps} />
+}

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

@@ -0,0 +1,53 @@
+{{={= =}=}}
+import { interpolatePath } from './linkHelpers'
+import type {
+  RouteDefinitionsToRoutes,
+  OptionalRouteOptions,
+  ParamValue,
+  ExpandRouteOnOptionalStaticSegments,
+} from './types'
+
+// PUBLIC API
+export const routes = {
+  {=# routes =}
+  {= name =}: {
+    to: "{= urlPath =}",
+    {=# hasUrlParams =}
+    build: (
+      options: OptionalRouteOptions
+      & { params: {{=# urlParams =}"{= name =}"{=# isOptional =}?{=/ isOptional =}: ParamValue;{=/ urlParams =}}}
+      {=# hasOptionalStaticSegments =}
+      & { path: ExpandRouteOnOptionalStaticSegments<"{= urlPath =}"> }
+      {=/ hasOptionalStaticSegments =}
+    ) => interpolatePath(
+        {=# hasOptionalStaticSegments =}options.path,{=/ hasOptionalStaticSegments =}
+        {=^ hasOptionalStaticSegments =}"{= urlPath =}",{=/ hasOptionalStaticSegments =}
+        options.params,
+        options?.search,
+        options?.hash
+      ),
+    {=/ hasUrlParams =}
+    {=^ hasUrlParams =}
+    build: (
+      options?:
+      OptionalRouteOptions
+      {=# hasOptionalStaticSegments =}
+      & { path: ExpandRouteOnOptionalStaticSegments<"{= urlPath =}"> }
+      {=/ hasOptionalStaticSegments =}
+    ) => interpolatePath(
+        {=# hasOptionalStaticSegments =}options.path,{=/ hasOptionalStaticSegments =}
+        {=^ hasOptionalStaticSegments =}"{= urlPath =}",{=/ hasOptionalStaticSegments =}
+        undefined,
+        options?.search,
+        options?.hash
+      ),
+    {=/ hasUrlParams =}
+  },
+  {=/ routes =}
+} as const;
+
+// PRIVATE API
+export type Routes = RouteDefinitionsToRoutes<typeof routes>
+
+// PUBLIC API
+export { Link } from './Link'

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

@@ -0,0 +1,48 @@
+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);
+}

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

@@ -0,0 +1,98 @@
+// PRIVATE API
+export type RouteDefinitionsToRoutes<Routes extends RoutesDefinition> =
+  RouteDefinitionsToRoutesObj<Routes>[keyof RouteDefinitionsToRoutesObj<Routes>]
+
+// PRIVATE API
+export type OptionalRouteOptions = {
+  search?: Search
+  hash?: string
+}
+
+// PRIVATE API
+export type ParamValue = string | number
+// PRIVATE API
+export type Params = { [name: string]: ParamValue }
+// PRIVATE API
+export type Search =
+  | string[][]
+  | Record<string, string>
+  | string
+  | URLSearchParams
+
+type RouteDefinitionsToRoutesObj<Routes extends RoutesDefinition> = {
+  [K in keyof Routes]: {
+    to: ExpandRouteOnOptionalStaticSegments<Routes[K]['to']>
+  } & ParamsFromBuildFn<Routes[K]['build']>
+}
+
+type RoutesDefinition = {
+  [name: string]: {
+    to: string
+    build: BuildFn
+  }
+}
+
+type BuildFn = (params: never) => string
+
+type ParamsFromBuildFn<BF extends BuildFn> = Parameters<BF>[0] extends {
+  params: infer Params
+}
+  ? { params: Params }
+  : { params?: never }
+
+// PRIVATE API (sdk)
+/**
+ * Optional static segments handling: expands routes with optional segments
+ * into multiple routes, one for each possible combination of optional segments.
+ *
+ * For example: /users/tasks?/:id? will be expanded into two routes:
+ * - /users/:id?
+ * - /users/tasks/:id?
+ */
+export type ExpandRouteOnOptionalStaticSegments<Route extends string> = JoinPath<
+  ExpandOptionalSegments<ParseSegments<SplitPath<NonEmptyString<Route>>>>
+>;
+
+type ParseSegments<T> = T extends [infer Head, ...infer Tail]
+  ? [_ParseSegment<Head>, ...ParseSegments<Tail>]
+  : T;
+
+type _ParseSegment<T> = T extends `:${infer P}`
+  ? // Param segment
+    { segment: T }
+  : T extends `${infer S}?`
+    ? // Optional segment
+      { optionalSegment: S }
+    : // Regular segment
+      { segment: T };
+
+type Segment = { segment: string };
+type OptionalSegment = { optionalSegment: string };
+
+type Elem = Segment | OptionalSegment;
+
+type ExpandOptionalSegments<T extends Elem[]> = T extends []
+  ? []
+  : T extends [infer First extends Elem, ...infer Rest extends Elem[]]
+    ? First extends Segment
+      ? [First["segment"], ...ExpandOptionalSegments<Rest>]
+      : First extends OptionalSegment
+        ? [First["optionalSegment"], ...ExpandOptionalSegments<Rest>] | ExpandOptionalSegments<Rest>
+        : []
+    : [];
+
+type SplitPath<S extends string> = S extends "/"
+  ? [""]
+  : S extends `${infer T}/${infer U}`
+    ? [T, ...SplitPath<U>]
+    : [S];
+
+type JoinPath<T extends string[]> = T extends [infer Only extends string]
+  ? Only extends ""
+    ? "/"
+    : Only
+  : T extends [infer First extends string, ...infer Rest extends string[]]
+    ? `${First}/${JoinPath<Rest>}`
+    : never;
+
+type NonEmptyString<S extends string> = S extends "" ? never : S;

package/data/Generator/templates/sdk/wasp/client/test/index.ts

@@ -0,0 +1 @@
+export { renderInContext, mockServer } from './vitest/helpers'

package/data/Generator/templates/sdk/wasp/client/test/vitest/helpers.tsx

@@ -0,0 +1,95 @@
+import { ReactElement, ReactNode } from 'react'
+import { rest, type ResponseResolver, type RestContext } from 'msw'
+import { setupServer, type SetupServer } from 'msw/node'
+import { BrowserRouter as Router } from 'react-router-dom'
+import { render, RenderResult, cleanup } from '@testing-library/react'
+import { QueryClient, QueryClientProvider } from '@tanstack/react-query'
+import { beforeAll, afterEach, afterAll } from 'vitest'
+import { Query } from 'wasp/client/operations/rpc'
+import { config } from 'wasp/client'
+import { HttpMethod, Route } from 'wasp/client'
+import { serialize } from 'wasp/core/serialization'
+
+// PRIVATE API
+export type MockQuery = <Input, Output, MockOutput extends Output>(
+  query: Query<Input, Output>,
+  resJson: MockOutput
+) => void
+
+// PRIVATE API
+export type MockApi = (route: Route, resJson: unknown) => void
+
+// PUBLIC API
+// Inspired by the Tanstack React Query helper:
+// https://github.com/TanStack/query/blob/4ae99561ca3383d6de3f4aad656a49ba4a17b57a/packages/react-query/src/__tests__/utils.tsx#L7-L26
+export function renderInContext(ui: ReactElement): RenderResult {
+  const client = new QueryClient()
+  const { rerender, ...result } = render(
+    <QueryClientProvider client={client}>
+      <Router>{ui}</Router>
+    </QueryClientProvider>
+  )
+  return {
+    ...result,
+    rerender: (rerenderUi: ReactNode) =>
+      rerender(
+        <QueryClientProvider client={client}>
+          <Router>{rerenderUi}</Router>
+        </QueryClientProvider>
+      ),
+  }
+}
+
+// PUBLIC API
+export function mockServer(): {
+  server: SetupServer
+  mockQuery: MockQuery
+  mockApi: MockApi
+} {
+  const server: SetupServer = setupServer()
+
+  beforeAll(() => server.listen())
+  afterEach(() => {
+    server.resetHandlers()
+    cleanup()
+  })
+  afterAll(() => server.close())
+
+  const mockQuery: MockQuery = (query, mockData) => {
+    const route = (query as unknown as { route: Route }).route
+    mockRoute(server, route, (_req, res, ctx) =>
+      res(ctx.json(serialize(mockData)))
+    )
+  }
+
+  const mockApi: MockApi = (route, mockData) => {
+    mockRoute(server, route, (_req, res, ctx) => res(ctx.json(mockData)))
+  }
+
+  return { server, mockQuery, mockApi }
+}
+
+function mockRoute(
+  server: SetupServer,
+  route: Route,
+  responseHandler: ResponseResolver<any, RestContext, any>
+) {
+  if (!Object.values(HttpMethod).includes(route.method)) {
+    throw new Error(
+      `Unsupported query method for mocking: ${
+        route.method
+      }. Supported method strings are: ${Object.values(HttpMethod).join(', ')}.`
+    )
+  }
+
+  const url = `${config.apiUrl}${route.path}`
+
+  const handlers: Record<HttpMethod, Parameters<typeof server.use>[0]> = {
+    [HttpMethod.Get]: rest.get(url, responseHandler),
+    [HttpMethod.Post]: rest.post(url, responseHandler),
+    [HttpMethod.Put]: rest.put(url, responseHandler),
+    [HttpMethod.Delete]: rest.delete(url, responseHandler),
+  }
+
+  server.use(handlers[route.method])
+}

package/data/Generator/templates/sdk/wasp/client/webSocket/WebSocketProvider.tsx

@@ -0,0 +1,77 @@
+{{={= =}=}}
+import { createContext, useState, useEffect, Context, ReactNode } from 'react'
+import { io, Socket } from 'socket.io-client'
+
+import { getSessionId } from 'wasp/client/api'
+import { apiEventsEmitter } from 'wasp/api/events'
+import { config } from 'wasp/client'
+
+import type { ClientToServerEvents, ServerToClientEvents } from 'wasp/server/webSocket';
+
+export type WebSocketContextValue = {
+  socket: typeof socket
+  isConnected: boolean
+}
+
+// PRIVATE API
+// TODO: In the future, it would be nice if users could pass more
+// options to `io`, likely via some `configFn`.
+export const socket: Socket<ServerToClientEvents, ClientToServerEvents> = io(
+  config.apiUrl,
+  {
+    transports: ['websocket'],
+    autoConnect: {= autoConnect =},
+  }
+)
+
+function refreshAuthToken() {
+  // NOTE: When we figure out how `auth: true` works for Operations, we should
+  // mirror that behavior here for WebSockets. Ref: https://github.com/wasp-lang/wasp/issues/1133
+  socket.auth = {
+    sessionId: getSessionId()
+  }
+
+  if (socket.connected) {
+    socket.disconnect()
+    socket.connect()
+  }
+}
+
+refreshAuthToken()
+apiEventsEmitter.on('sessionId.set', refreshAuthToken)
+apiEventsEmitter.on('sessionId.clear', refreshAuthToken)
+
+// PRIVATE API
+export const WebSocketContext: Context<WebSocketContextValue> = createContext<WebSocketContextValue>({
+  socket,
+  isConnected: false,
+});
+
+// PRIVATE API
+export function WebSocketProvider({ children }: { children: ReactNode }) {
+  const [isConnected, setIsConnected] = useState(socket.connected)
+
+  useEffect(() => {
+    function onConnect() {
+      setIsConnected(true)
+    }
+
+    function onDisconnect() {
+      setIsConnected(false)
+    }
+
+    socket.on('connect', onConnect)
+    socket.on('disconnect', onDisconnect)
+
+    return () => {
+      socket.off('connect', onConnect)
+      socket.off('disconnect', onDisconnect)
+    }
+  }, [])
+
+  return (
+    <WebSocketContext.Provider value={{ socket, isConnected }}>
+      {children}
+    </WebSocketContext.Provider>
+  );
+}

package/data/Generator/templates/sdk/wasp/client/webSocket/index.ts

@@ -0,0 +1,39 @@
+import { useContext, useEffect } from 'react'
+import { WebSocketContext, WebSocketContextValue } from './WebSocketProvider'
+import type {
+  ClientToServerEvents,
+  ServerToClientEvents,
+} from 'wasp/server/webSocket'
+
+// PUBLIC API
+export type ServerToClientPayload<Event extends keyof ServerToClientEvents> =
+  Parameters<ServerToClientEvents[Event]>[0]
+// PUBLIC API
+export type ClientToServerPayload<Event extends keyof ClientToServerEvents> =
+  Parameters<ClientToServerEvents[Event]>[0]
+
+// PUBLIC API
+export function useSocket(): WebSocketContextValue {
+  return useContext(WebSocketContext)
+}
+
+// PUBLIC API
+export function useSocketListener<Event extends keyof ServerToClientEvents>(
+  event: Event,
+  handler: ServerToClientEvents[Event]
+): void {
+  const { socket } = useContext(WebSocketContext)
+  useEffect(() => {
+    // Casting to `keyof ServerToClientEvents` is necessary because TypeScript
+    // reports the handler function as incompatible with the event type.
+    // See https://github.com/wasp-lang/wasp/pull/1203#discussion_r1232068898
+
+    // We are wrapping it in `Extract<...>` due to Typescript infering string | number
+    // in the case of default events being used.
+    type AllowedEvents = Extract<keyof ServerToClientEvents, string>;
+    socket.on(event as AllowedEvents, handler)
+    return () => {
+      socket.off(event as AllowedEvents, handler)
+    }
+  }, [event, handler])
+}