@farm.js/core 0.1.0-beta.1 → 0.1.0-beta.11

package/types/client.d.ts

@@ -3,16 +3,20 @@
  *
  * Provides stable exports for Link, useRouter, and API client so TypeScript
  * and IDEs resolve them even when the build output omits them. The generated
- * farm-routes.d.ts in your app augments LinkDefaultRoute for typed href.
+ * farm.d.ts in your app augments LinkDefaultRoute for typed href.
  */
 
 import type {
   AnchorHTMLAttributes,
+  ComponentType,
+  FormEvent,
+  FormHTMLAttributes,
   ReactElement,
   ReactNode,
   RefObject,
   RefAttributes,
 } from "react";
+import type { DefinedCacheKey, InferCacheKeyData, RouteDataCacheKey } from "@farm.js/core/cache";
 
 declare module "@farm.js/core/client" {
   export interface MiddlewareProps {
@@ -378,6 +382,36 @@ declare module "@farm.js/core/client" {
     key: CacheKey<TData>;
   };
 
+  export interface FarmAPIStream<TItem> extends AsyncIterable<TItem> {
+    readonly response: Response;
+    cancel(reason?: unknown): Promise<void>;
+  }
+
+  export class APIClientError<
+    TCode extends string = string,
+    TData = unknown,
+    TStatus extends number = number,
+  > extends Error {
+    readonly code: TCode;
+    readonly data: TData;
+    readonly status: TStatus;
+    readonly response?: Response;
+
+    constructor(
+      code: TCode,
+      data: TData,
+      options: {
+        status: TStatus;
+        message: string;
+        response?: Response;
+      },
+    );
+  }
+
+  export type APIClientSystemError =
+    | APIClientError<"http_error", unknown, number>
+    | APIClientError<"network_error", unknown, 0>;
+
   export type RequestEvent = {
     requestId: string;
     method: StatusEvent["method"];
@@ -406,7 +440,7 @@ declare module "@farm.js/core/client" {
   export type CachePolicy = "cache-first" | "network-only" | "stale-while-revalidate";
 
   export type CacheOptions = {
-    key?: string;
+    key?: RouteDataCacheKey;
     policy?: CachePolicy;
     staleTime?: number;
     gcTime?: number;
@@ -419,9 +453,9 @@ declare module "@farm.js/core/client" {
   };
 
   export type InvalidateTarget =
-    | string
+    | RouteDataCacheKey
     | {
-        key: string;
+        key: RouteDataCacheKey;
       }
     | {
         path: string;
@@ -439,7 +473,7 @@ declare module "@farm.js/core/client" {
 
   export type OptimisticUpdate =
     | [CallableRouteRef<any>, unknown, (prev: any) => any]
-    | [CacheKey<any> | string, (prev: any) => any];
+    | [CacheKey<any> | DefinedCacheKey<any> | string, (prev: any) => any];
 
   export type OptimisticOptions<TUpdates extends readonly unknown[] = readonly OptimisticUpdate[]> =
     {
@@ -452,7 +486,7 @@ declare module "@farm.js/core/client" {
     TError = unknown,
     TUpdates extends readonly unknown[] = readonly OptimisticUpdate[],
   > = {
-    key?: CacheKey<TData> | string;
+    key?: CacheKey<TData> | RouteDataCacheKey;
     cache?: CacheOptions;
     retry?: RetryOptions;
     invalidate?: InvalidateOptions;
@@ -496,11 +530,13 @@ declare module "@farm.js/core/client" {
         ]
       : never
     : TUpdate extends readonly [infer TKey, (prev: any) => any]
-      ? TKey extends CacheKey<infer TData>
-        ? [TKey, (prev: TData | undefined) => TData]
-        : TKey extends string
-          ? [TKey, (prev: unknown) => unknown]
-          : never
+      ? TKey extends DefinedCacheKey<any, RouteDataCacheKey>
+        ? [TKey, (prev: InferCacheKeyData<TKey> | undefined) => InferCacheKeyData<TKey>]
+        : TKey extends CacheKey<infer TData>
+          ? [TKey, (prev: TData | undefined) => TData]
+          : TKey extends string
+            ? [TKey, (prev: unknown) => unknown]
+            : never
       : never;
 
   type NormalizeOptimisticUpdates<TUpdates extends readonly unknown[]> = {
@@ -514,8 +550,10 @@ declare module "@farm.js/core/client" {
   type TypedEndpointLike = {
     __types: {
       body: any;
+      inputBody?: any;
       query: any;
       response: any;
+      errors?: any;
     };
   };
 
@@ -554,13 +592,26 @@ declare module "@farm.js/core/client" {
   type HasRequiredKeys<T> = RequiredKeys<T> extends never ? false : true;
 
   // Type utilities to extract endpoint input/output types
+  type InferEndpointBody<T> = T extends {
+    __types: {
+      inputBody: infer TInputBody;
+    };
+  }
+    ? TInputBody
+    : T extends {
+          __types: {
+            body: infer TBody;
+          };
+        }
+      ? TBody
+      : never;
+
   type InferEndpointInput<T> = T extends {
     __types: {
-      body: infer TBody;
       query: infer TQuery;
     };
   }
-    ? SimplifyEndpointInput<BodyInputProp<TBody> & QueryInputProp<TQuery>>
+    ? SimplifyEndpointInput<BodyInputProp<InferEndpointBody<T>> & QueryInputProp<TQuery>>
     : {};
 
   type InferEndpointOutput<T> = T extends {
@@ -568,24 +619,177 @@ declare module "@farm.js/core/client" {
       response: infer R;
     };
   }
-    ? R
+    ? R extends { readonly __farmStreamItem: infer TItem }
+      ? FarmAPIStream<TItem>
+      : R
     : any;
 
+  type InferEndpointError<T> = T extends {
+    __types: {
+      errors: infer TErrors;
+    };
+  }
+    ? keyof TErrors extends never
+      ? Error
+      :
+          | {
+              [TCode in keyof TErrors]: TErrors[TCode] extends {
+                data: infer TData;
+                status: infer TStatus extends number;
+              }
+                ? APIClientError<TCode & string, TData, TStatus>
+                : never;
+            }[keyof TErrors]
+          | APIClientSystemError
+    : Error;
+
   type EndpointMethod<T = any> = (<
     TUpdates extends readonly unknown[] = readonly OptimisticUpdate[],
   >(
     ...args: HasRequiredKeys<InferEndpointInput<T>> extends true
       ? [
           options: InferEndpointInput<T>,
-          clientOptions?: ClientOptions<InferEndpointOutput<T>, Error, TUpdates>,
+          clientOptions?: ClientOptions<InferEndpointOutput<T>, InferEndpointError<T>, TUpdates>,
         ]
       : [
           options?: InferEndpointInput<T>,
-          clientOptions?: ClientOptions<InferEndpointOutput<T>, Error, TUpdates>,
+          clientOptions?: ClientOptions<InferEndpointOutput<T>, InferEndpointError<T>, TUpdates>,
         ]
-  ) => Promise<APIResult<InferEndpointOutput<T>, Error>>) &
+  ) => Promise<APIResult<InferEndpointOutput<T>, InferEndpointError<T>>>) &
     RouteRef<InferEndpointOutput<T>, InferEndpointInput<T>>;
 
+  export type MutationStatus = "idle" | "pending" | "success" | "error";
+
+  export type AnyMutationTarget = (...args: any[]) => Promise<any>;
+
+  export type InferMutationVariables<TTarget extends AnyMutationTarget> =
+    Parameters<TTarget> extends [] ? undefined : Parameters<TTarget>[0];
+
+  export type InferMutationData<TTarget extends AnyMutationTarget> = TTarget extends {
+    readonly __farmRouteData: infer TData;
+  }
+    ? TData
+    : Awaited<ReturnType<TTarget>>;
+
+  export type InferMutationError<TTarget extends AnyMutationTarget> = TTarget extends (
+    ...args: any[]
+  ) => Promise<APIResult<any, infer TError>>
+    ? TError
+    : Error;
+
+  export type MutationOptimisticContext<TVariables, TData> = {
+    variables: TVariables | undefined;
+    current: TData | null;
+  };
+
+  export type UseMutationOptions<TVariables, TData, TError = Error> = {
+    initialData?: TData | null;
+    resetOnMutate?: boolean;
+    optimistic?: (
+      context: MutationOptimisticContext<TVariables, TData>,
+    ) => TData | null | undefined;
+    rollbackOnError?: boolean;
+    request?: ClientOptions<TData, TError>;
+    onSuccess?: (data: TData, variables: TVariables | undefined) => void;
+    onError?: (error: TError, variables: TVariables | undefined) => void;
+    onSettled?: (
+      data: TData | null,
+      error: TError | null,
+      variables: TVariables | undefined,
+    ) => void;
+  };
+
+  export type MutationAsync<TTarget extends AnyMutationTarget, TData = InferMutationData<TTarget>> =
+    [] extends Parameters<TTarget>
+      ? (variables?: InferMutationVariables<TTarget>) => Promise<TData>
+      : (variables: InferMutationVariables<TTarget>) => Promise<TData>;
+
+  export type MutationTrigger<TTarget extends AnyMutationTarget> =
+    [] extends Parameters<TTarget>
+      ? (variables?: InferMutationVariables<TTarget>) => void
+      : (variables: InferMutationVariables<TTarget>) => void;
+
+  export type UseMutationReturn<
+    TTarget extends AnyMutationTarget,
+    TData = InferMutationData<TTarget>,
+    TError = InferMutationError<TTarget>,
+  > = {
+    pending: boolean;
+    status: MutationStatus;
+    data: TData | null;
+    error: TError | null;
+    variables: InferMutationVariables<TTarget> | undefined;
+    mutate: MutationTrigger<TTarget>;
+    mutateAsync: MutationAsync<TTarget, TData>;
+    reset: () => void;
+  };
+
+  export function useMutation<TTarget extends AnyMutationTarget>(
+    target: TTarget,
+    options?: UseMutationOptions<
+      InferMutationVariables<TTarget>,
+      InferMutationData<TTarget>,
+      InferMutationError<TTarget>
+    >,
+  ): UseMutationReturn<TTarget>;
+
+  export type FetcherState = "idle" | "submitting";
+
+  export type FetcherFormDataContext = {
+    form: HTMLFormElement | null;
+    submitter: HTMLElement | null;
+  };
+
+  export type UseFetcherOptions<TTarget extends AnyMutationTarget> = UseMutationOptions<
+    InferMutationVariables<TTarget>,
+    InferMutationData<TTarget>,
+    InferMutationError<TTarget>
+  > & {
+    mapFormData?: (
+      formData: FormData,
+      context: FetcherFormDataContext,
+    ) => InferMutationVariables<TTarget>;
+  };
+
+  export type FetcherFormProps = Omit<
+    FormHTMLAttributes<HTMLFormElement>,
+    "action" | "onSubmit"
+  > & {
+    action?: string | ((formData: FormData) => void | Promise<void>);
+    onSubmit?: (event: FormEvent<HTMLFormElement>) => void;
+  };
+
+  type FetcherInput<TTarget extends AnyMutationTarget> = InferMutationVariables<TTarget> | FormData;
+
+  export type FetcherSubmitAsync<TTarget extends AnyMutationTarget> =
+    [] extends Parameters<TTarget>
+      ? (input?: FetcherInput<TTarget>) => Promise<InferMutationData<TTarget>>
+      : (input: FetcherInput<TTarget>) => Promise<InferMutationData<TTarget>>;
+
+  export type FetcherSubmit<TTarget extends AnyMutationTarget> =
+    [] extends Parameters<TTarget>
+      ? (input?: FetcherInput<TTarget>) => void
+      : (input: FetcherInput<TTarget>) => void;
+
+  export type UseFetcherReturn<TTarget extends AnyMutationTarget> = {
+    state: FetcherState;
+    status: MutationStatus;
+    pending: boolean;
+    data: InferMutationData<TTarget> | null;
+    error: InferMutationError<TTarget> | null;
+    variables: InferMutationVariables<TTarget> | undefined;
+    formData: FormData | null;
+    submit: FetcherSubmit<TTarget>;
+    submitAsync: FetcherSubmitAsync<TTarget>;
+    Form: ComponentType<FetcherFormProps>;
+    reset: () => void;
+  };
+
+  export function useFetcher<TTarget extends AnyMutationTarget>(
+    target: TTarget,
+    options?: UseFetcherOptions<TTarget>,
+  ): UseFetcherReturn<TTarget>;
+
   type RouterToClient<T> = {
     [K in keyof T]: T[K] extends TypedEndpointLike
       ? EndpointMethod<T[K]>

package/types/image.d.ts

@@ -0,0 +1,4 @@
+/// <reference path="./images.d.ts" />
+
+export * from "../dist/image";
+export { default } from "../dist/image";

package/types/images.d.ts

@@ -0,0 +1,59 @@
+/** Static image imports available to every Farm application. */
+declare module "*.avif" {
+  const image: import("@farm.js/core/image").StaticImageData;
+  export const src: string;
+  export const width: number;
+  export const height: number;
+  export const blurDataURL: string | undefined;
+  export default image;
+}
+
+declare module "*.gif" {
+  const image: import("@farm.js/core/image").StaticImageData;
+  export const src: string;
+  export const width: number;
+  export const height: number;
+  export const blurDataURL: string | undefined;
+  export default image;
+}
+
+declare module "*.jpeg" {
+  const image: import("@farm.js/core/image").StaticImageData;
+  export const src: string;
+  export const width: number;
+  export const height: number;
+  export const blurDataURL: string | undefined;
+  export default image;
+}
+
+declare module "*.jpg" {
+  const image: import("@farm.js/core/image").StaticImageData;
+  export const src: string;
+  export const width: number;
+  export const height: number;
+  export const blurDataURL: string | undefined;
+  export default image;
+}
+
+declare module "*.png" {
+  const image: import("@farm.js/core/image").StaticImageData;
+  export const src: string;
+  export const width: number;
+  export const height: number;
+  export const blurDataURL: string | undefined;
+  export default image;
+}
+
+declare module "*.webp" {
+  const image: import("@farm.js/core/image").StaticImageData;
+  export const src: string;
+  export const width: number;
+  export const height: number;
+  export const blurDataURL: string | undefined;
+  export default image;
+}
+
+declare module "*?url" {
+  const src: string;
+  export default src;
+}