@sugardarius/anzen 2.2.0 → 2.3.0

package/dist/index.d.cts

@@ -1,5 +1,196 @@
-import { A as AuthContext, T as TSegmentsDict, a as TSearchParamsDict, b as TBodySchema, c as TFormDataDict, C as CreateSafeRouteHandlerOptions, S as SafeRouteHandler, d as CreateSafeRouteHandlerReturnType } from './types-LPIIICMI.cjs';
-export { f as AuthFunction, g as AuthFunctionParams, e as Awaitable, B as BaseOptions, O as OnValidationErrorResponse, P as ProvidedRouteContext, h as SafeRouteHandlerContext } from './types-LPIIICMI.cjs';
+import { A as AuthContext, S as StandardSchemaDictionary, a as StandardSchemaV1, b as Awaitable, U as UnwrapReadonlyObject, E as EmptyObjectType } from './standard-schema-BHEkWkzf.cjs';
+
+type TSegmentsDict = StandardSchemaDictionary;
+type TSearchParamsDict = StandardSchemaDictionary;
+type TBodySchema = StandardSchemaV1;
+type TFormDataDict = StandardSchemaDictionary;
+type RouteHandlerAuthFunctionParams<TSegments extends TSegmentsDict | undefined, TSearchParams extends TSearchParamsDict | undefined, TBody extends TBodySchema | undefined, TFormData extends TFormDataDict | undefined> = {
+    /**
+     * ID for the route handler.
+     */
+    readonly id: string;
+    /**
+     * Parsed request url
+     */
+    readonly url: URL;
+    /**
+     * Original request
+     *
+     * Cloned from the incoming request to avoid side effects
+     * and to make it consumable in the `authorize` function.
+     * Due to `NextRequest` limitations as the req is cloned it's always a `Request`
+     */
+    req: Request;
+} & (TSegments extends TSegmentsDict ? {
+    /**
+     * Validated route dynamic segments
+     */
+    readonly segments: UnwrapReadonlyObject<StandardSchemaDictionary.InferOutput<TSegments>>;
+} : EmptyObjectType) & (TSearchParams extends TSearchParamsDict ? {
+    /**
+     * Validated search params
+     */
+    readonly searchParams: UnwrapReadonlyObject<StandardSchemaDictionary.InferOutput<TSearchParams>>;
+} : EmptyObjectType) & (TBody extends TBodySchema ? {
+    /**
+     * Validated request body
+     */
+    readonly body: StandardSchemaV1.InferOutput<TBody>;
+} : EmptyObjectType) & (TFormData extends TFormDataDict ? {
+    /**
+     * Validated form data
+     */
+    readonly formData: UnwrapReadonlyObject<StandardSchemaDictionary.InferOutput<TFormData>>;
+} : EmptyObjectType);
+type RouteHandlerAuthFunction<AC extends AuthContext | undefined, TSegments extends TSegmentsDict | undefined, TSearchParams extends TSearchParamsDict | undefined, TBody extends TBodySchema | undefined, TFormData extends TFormDataDict | undefined> = (params: RouteHandlerAuthFunctionParams<TSegments, TSearchParams, TBody, TFormData>) => Awaitable<AC | Response | never>;
+type OnValidationErrorResponse = (issues: readonly StandardSchemaV1.Issue[]) => Awaitable<Response>;
+type CreateSafeRouteHandlerOptions<AC extends AuthContext | undefined, TSegments extends TSegmentsDict | undefined, TSearchParams extends TSearchParamsDict | undefined, TBody extends TBodySchema | undefined, TFormData extends TFormDataDict | undefined> = {
+    /**
+     * ID for the route handler.
+     * Used when logging in development or when `debug` is enabled.
+     *
+     * You can also use it to add extra logging or monitoring.
+     */
+    id?: string;
+    /**
+     * Callback triggered when the request fails.
+     * By default it returns a simple `500` response and the error is logged into the console.
+     *
+     * Use it if your handler use custom errors and
+     * you want to manage them properly by returning a proper response.
+     */
+    onErrorResponse?: (err: unknown) => Awaitable<Response>;
+    /**
+     * Use this options to enable debug mode.
+     * It will add logs in the handler to help you debug the request.
+     *
+     * By default it's set to `false` for production builds.
+     * In development builds, it will be `true` if `NODE_ENV` is not set to `production`.
+     */
+    debug?: boolean;
+    /**
+     * Dynamic route segments used for the route handler path.
+     * By design it will handler if the segments are a `Promise` or not.
+     *
+     * Please note the expected input is a `StandardSchemaDictionary`.
+     */
+    segments?: TSegments;
+    /**
+     * Callback triggered when dynamic segments validations returned issues.
+     * By default it returns a simple `400` response and issues are logged into the console.
+     */
+    onSegmentsValidationErrorResponse?: OnValidationErrorResponse;
+    /**
+     * Search params used in the route.
+     *
+     * Please note the expected input is a `StandardSchemaDictionary`.
+     */
+    searchParams?: TSearchParams;
+    /**
+     * Callback triggered when search params validations returned issues.
+     * By default it returns a simple `400` response and issues are logged into the console.
+     */
+    onSearchParamsValidationErrorResponse?: OnValidationErrorResponse;
+    /**
+     * Request body.
+     *
+     * Returns a `405` response if the request method is not `POST`, 'PUT' or 'PATCH'.
+     * Returns a `415`response if the request does not explicitly set the `Content-Type` to `application/json`.
+     *
+     * IMPORTANT: The body is parsed as JSON, so it must be a valid JSON object!
+     * IMPORTANT: Body shouldn't be used with `formData` at the same time. They are exclusive.
+     * Why making the distinction? `formData` is used as a `StandardSchemaDictionary` whereas `body` is used as a `StandardSchemaV1`.
+     */
+    body?: TBody;
+    /**
+     * Callback triggered when body validation returned issues.
+     * By default it returns a simple `400` response and issues are logged into the console.
+     */
+    onBodyValidationErrorResponse?: OnValidationErrorResponse;
+    /**
+     * Request form data.
+     *
+     * Returns a `405` response if the request method is not `POST`, 'PUT' or 'PATCH'.
+     * Returns a `415`response if the request does not explicitly set the `Content-Type` to `multipart/form-data`
+     * or to `application/x-www-form-urlencoded`.
+     *
+     * IMPORTANT: formData shouldn't be used with `body` at the same time. They are exclusive.
+     * Why making the distinction? `formData` is used as a `StandardSchemaDictionary` whereas `body` is used as a `StandardSchemaV1`.
+     */
+    formData?: TFormData;
+    /**
+     * Callback triggered when form data validation returned issues.
+     * By default it returns a simple `400` response and issues are logged into the console.
+     */
+    onFormDataValidationErrorResponse?: OnValidationErrorResponse;
+    /**
+     * Function to use to authorize the request.
+     * By default it always authorize the request.
+     *
+     * When returning a response, it will be used as the response for the request.
+     * Return a response when the request is not authorized.
+     */
+    authorize?: RouteHandlerAuthFunction<AC, TSegments, TSearchParams, TBody, TFormData>;
+};
+type ProvidedRouteContext = {
+    /**
+     * Route dynamic segments as params
+     */
+    params: Awaitable<any> | undefined;
+};
+type CreateSafeRouteHandlerReturnType<TReq extends Request = Request> = (
+/**
+ * Original request
+ */
+req: TReq, 
+/**
+ * Provided context added by Next.js itself
+ */
+providedContext: ProvidedRouteContext) => Promise<Response | never>;
+type SafeRouteHandlerContext<AC extends AuthContext | undefined, TSegments extends TSegmentsDict | undefined, TSearchParams extends TSearchParamsDict | undefined, TBody extends TBodySchema | undefined, TFormData extends TFormDataDict | undefined> = {
+    /**
+     * Route handler ID
+     */
+    readonly id: string;
+    /**
+     * Parsed request url
+     */
+    readonly url: URL;
+} & (AC extends AuthContext ? {
+    /**
+     * Auth context
+     */
+    readonly auth: AC;
+} : EmptyObjectType) & (TSegments extends TSegmentsDict ? {
+    /**
+     * Validated route dynamic segments
+     */
+    readonly segments: UnwrapReadonlyObject<StandardSchemaDictionary.InferOutput<TSegments>>;
+} : EmptyObjectType) & (TSearchParams extends TSearchParamsDict ? {
+    /**
+     * Validated search params
+     */
+    readonly searchParams: UnwrapReadonlyObject<StandardSchemaDictionary.InferOutput<TSearchParams>>;
+} : EmptyObjectType) & (TBody extends TBodySchema ? {
+    /**
+     * Validated request body
+     */
+    readonly body: StandardSchemaV1.InferOutput<TBody>;
+} : EmptyObjectType) & (TFormData extends TFormDataDict ? {
+    /**
+     * Validated form data
+     */
+    readonly formData: UnwrapReadonlyObject<StandardSchemaDictionary.InferOutput<TFormData>>;
+} : EmptyObjectType);
+type SafeRouteHandler<AC extends AuthContext | undefined, TSegments extends TSegmentsDict | undefined, TSearchParams extends TSearchParamsDict | undefined, TBody extends TBodySchema | undefined, TFormData extends TFormDataDict | undefined, TReq extends Request = Request> = (
+/**
+ * Safe route handler context
+ */
+ctx: SafeRouteHandlerContext<AC, TSegments, TSearchParams, TBody, TFormData>, 
+/**
+ * Original request
+ */
+req: TReq) => Promise<Response | never>;
 
 /**
  * Creates a safe route handler with data validation and error handling
@@ -13,7 +204,7 @@ export { f as AuthFunction, g as AuthFunctionParams, e as Awaitable, B as BaseOp
  * @example
  * ```ts
  * import { string } from 'decoders'
- *import { createSafeRouteHandler } from '@sugardarius/anzen'
+ * import { createSafeRouteHandler } from '@sugardarius/anzen'
  * import { auth } from '~/lib/auth'
  *
  * export const GET = createSafeRouteHandler(
@@ -39,4 +230,263 @@ export { f as AuthFunction, g as AuthFunctionParams, e as Awaitable, B as BaseOp
  */
 declare function createSafeRouteHandler<AC extends AuthContext | undefined = undefined, TRouteDynamicSegments extends TSegmentsDict | undefined = undefined, TSearchParams extends TSearchParamsDict | undefined = undefined, TBody extends TBodySchema | undefined = undefined, TFormData extends TFormDataDict | undefined = undefined, TReq extends Request = Request>(options: CreateSafeRouteHandlerOptions<AC, TRouteDynamicSegments, TSearchParams, TBody, TFormData>, handlerFn: SafeRouteHandler<AC, TRouteDynamicSegments, TSearchParams, TBody, TFormData, TReq>): CreateSafeRouteHandlerReturnType<TReq>;
 
-export { AuthContext, CreateSafeRouteHandlerOptions, CreateSafeRouteHandlerReturnType, SafeRouteHandler, TBodySchema, TFormDataDict, TSearchParamsDict, TSegmentsDict, createSafeRouteHandler };
+type TInputSchema = StandardSchemaV1;
+type ServerActionErrorContext = Record<string, unknown>;
+/**
+ * Generic server error.
+ * Triggered when server action handler throws an unexpected error.
+ *
+ * Context `ctx` is used to store the error context.
+ * It can be customized by using the `onError` option when creating the server action.
+ */
+type ServerError = {
+    readonly code: 'SERVER_ERROR';
+    readonly ctx: ServerActionErrorContext;
+};
+/**
+ * Unauthorized error.
+ * Triggered when server action is not authorized by the `authorize` function
+ * 👉🏻 When `authorize` function throws an error.
+ *
+ *
+ * Context `ctx` is used to store the error context.
+ * It can be customized by using the `onError` option when creating the server action.
+ */
+type UnauthorizedError = {
+    readonly code: 'UNAUTHORIZED_ERROR';
+    readonly ctx: ServerActionErrorContext;
+};
+/**
+ * Validation error.
+ * Triggered when server action input validation returns issues.
+ *
+ * Context `ctx` is used to store the error context.
+ * It can be customized by using the `onInputValidationError` option when creating the server action.
+ *
+ * By default this error will return the issues `StandardSchemaV1.Issue[]` in the context when
+ * no context customization is provided.
+ */
+type ValidationError = {
+    readonly code: 'VALIDATION_ERROR';
+    readonly ctx: ServerActionErrorContext;
+};
+/**
+ * Tagged error.
+ * It represents an error expected to be used in the server action
+ * defined by developers themselves.
+ */
+type TaggedError = {
+    readonly code: string;
+    readonly ctx: ServerActionErrorContext;
+};
+type SafeServerActionError = ValidationError | UnauthorizedError | ServerError | TaggedError;
+type SafeServerActionResultSuccess<TOutput> = {
+    readonly success: true;
+    readonly output: TOutput;
+    readonly error?: never;
+};
+type SafeServerActionResultError<TError> = {
+    readonly success: false;
+    readonly output?: never;
+    readonly error: TError;
+};
+type ServerActionAuthFunctionParams<TInput extends TInputSchema | undefined> = {
+    /**
+     * Server action ID
+     */
+    readonly id: string;
+} & (TInput extends TInputSchema ? {
+    /**
+     * Validated input
+     */
+    readonly input: UnwrapReadonlyObject<StandardSchemaV1.InferOutput<TInput>>;
+} : EmptyObjectType);
+type ServerActionAuthFunction<AC extends AuthContext | undefined, TInput extends TInputSchema | undefined> = (
+/**
+ * Auth function parameters
+ * Contains the server action ID and the validated input.
+ *
+ * If the input is not provided, the property do not exists.
+ *
+ * @example
+ * ```ts
+ * authorize: async ({ id, input }) => {
+ *  const auth = await getAuth()
+ *  if (!auth) {
+ *    throw new UnauthenticatedError()
+ *  }
+ *
+ *  const hasAccess = await checkAccess({
+ *    userId: auth.user.id,
+ *    resourceId: input.resourceId,
+ *  })
+ *
+ *  if (!hasAccess) {
+ *    throw new ForbiddenError()
+ *  }
+ *
+ *  return { user: auth.user }
+ * }
+ * ```
+ */
+params: ServerActionAuthFunctionParams<TInput>) => Awaitable<AC | never>;
+type OnError = (err: unknown) => Awaitable<ServerActionErrorContext>;
+type OnInputValidationError = (issues: readonly StandardSchemaV1.Issue[]) => Awaitable<ServerActionErrorContext>;
+type CreateSafeServerActionOptions<TInput extends TInputSchema | undefined, AC extends AuthContext | undefined> = {
+    /**
+     * ID for the server action.
+     * Used when logging in development or when `debug` is enabled.
+     *
+     * You can also use it to add extra logging or monitoring.
+     */
+    id?: string;
+    /**
+     * Use this options to enable debug mode.
+     * It will add logs in the handler to help you debug server action.
+     *
+     * By default it's set to `false` for production builds.
+     * In development builds, it will be `true` if `NODE_ENV` is not set to `production`.
+     */
+    debug?: boolean;
+    /**
+     * Callback triggered when the server action throws an unhandled error.
+     * By default it will return an error context object and the error is logged into the console.
+     *
+     * Use it if you want to manage unexpected errors properly
+     * to log or trace and define custom error contexts objects.
+     *
+     * ⚠️ By design, this callback isn't mean to be used to manage navigation behaviors like using `notFound` or `redirect`,
+     * or with `throw` statements as it's best to handle them in the UI. ⚠️
+     *
+     * @example
+     * ```ts
+     * // ✅ Valid use case
+     * onError: async (err: unknown) => {
+     *  log.error(`🛑 Unexpected error in server action '${id}'`, err)
+     *  if (err instanceof NotFoundError) {
+     *    return {
+     *      message: 'Resource not found',
+     *    }
+     *  }
+     *
+     *  return {
+     *    message: 'An unexpected error occurred',
+     *    err: JSON.stringify(err),
+     *  }
+     * }
+     *
+     * // ❌ Invalid use case
+     * onError: async (err: unknown) => {
+     *  throw err
+     *  // or redirect('/')
+     * }
+     */
+    onError?: OnError;
+    /**
+     * Server action input schema used to validate the input
+     * when calling the server action.
+     *
+     * Please note the expected input is a `StandardSchemaV1`.
+     */
+    input?: TInput;
+    /**
+     * Callback triggered when input validation returned issues
+     *  By default it will return an error context object and the error is logged into the console.
+     *
+     * Use it if you want to manage input validation errors properly
+     * to log or trace and define custom error contexts objects.
+     *
+     * ⚠️ By design, this callback isn't mean to be used to manage navigation behaviors like using `notFound` or `redirect`,
+     * or with `throw` statements as it's best to handle them in the UI. ⚠️
+     *
+     * @example
+     * ```ts
+     * // ✅ Valid use case
+     * onInputValidationError: async (issues: readonly StandardSchemaV1.Issue[]) => {
+     *  log.error(`🛑 Invalid input for server action '${id}'`, issues)
+     *  return {
+     *    message: 'Invalid input',
+     *    issues,
+     *  }
+     * }
+     *
+     * // ❌ Invalid use case
+     * onInputValidationError: async (issues: readonly StandardSchemaV1.Issue[]) => {
+     *  throw new Error('Invalid input')
+     * }
+     * ```
+     */
+    onInputValidationError?: OnInputValidationError;
+    /**
+     * Function to use to authorize the server action.
+     * By default it always authorize the server action.
+     *
+     * Returns an unauthorized error when the server action is not authorized
+     * or never when `redirect`, `notFound`, `forbidden` or `unauthorized` are thrown.
+     */
+    authorize?: ServerActionAuthFunction<AC, TInput>;
+};
+type SafeServerActionResult<TOutput, TError> = SafeServerActionResultSuccess<TOutput> | SafeServerActionResultError<TError> | never;
+type InferServerActionProvidedInput<TInput extends TInputSchema | undefined> = TInput extends TInputSchema ? FormData | StandardSchemaV1.InferOutput<TInput> : undefined;
+type CreateSafeServerActionReturnType<TInput extends TInputSchema | undefined, TOutput, TError> = [TInput] extends [TInputSchema] ? (providedInput: InferServerActionProvidedInput<TInput>) => Promise<SafeServerActionResult<TOutput, TError>> : (providedInput?: InferServerActionProvidedInput<TInput>) => Promise<SafeServerActionResult<TOutput, TError>>;
+type SafeServerActionContext<TInput extends TInputSchema | undefined, AC extends AuthContext | undefined> = {
+    /**
+     * Server action ID
+     */
+    readonly id: string;
+    /**
+     * Tag error function
+     * Throws a developer defined tagged error.
+     * @example
+     * ```ts
+     * // Server
+     * export const myAction = createSafeServerAction({
+     *  id: 'my action,
+     * }, async ({ tagErr }) => {
+     *  tagErr('CONFLICT', {
+     *    message: 'resource already exists',
+     *  })
+     * })
+     *
+     * // Client
+     * const result = await myAction()
+     * if (result.success === false) {
+     *  if (result.error.code === 'CONFLICT') {
+     *    return <span>{result.error.ctx.message}</span>
+     *  }
+     * }
+     * ```
+     */
+    readonly tagErr: (code: string, ctx: ServerActionErrorContext) => never;
+} & (AC extends AuthContext ? {
+    /**
+     * Auth context
+     */
+    readonly auth: AC;
+} : EmptyObjectType) & (TInput extends TInputSchema ? {
+    /**
+     * Validated input
+     */
+    readonly input: UnwrapReadonlyObject<StandardSchemaV1.InferOutput<TInput>>;
+} : EmptyObjectType);
+type SafeServerActionHandler<TOutput, TInput extends TInputSchema | undefined, AC extends AuthContext | undefined> = (
+/**
+ * Safe server action context
+ */
+ctx: SafeServerActionContext<TInput, AC>) => Promise<TOutput | never>;
+
+/**
+ * Overload for server actions with no input.
+ * Used when calling server actions with no input schema provided,
+ * making the DX for developers easier and nicer. It avoids to call
+ * a server action with `undefined` as input.
+ */
+declare function createSafeServerAction<TOutput, AC extends AuthContext | undefined = undefined>(options: CreateSafeServerActionOptions<undefined, AC>, handler: SafeServerActionHandler<TOutput, undefined, AC>): CreateSafeServerActionReturnType<undefined, TOutput, SafeServerActionError>;
+/**
+ * Overload for server actions with input.
+ */
+declare function createSafeServerAction<TOutput, TInput extends TInputSchema, AC extends AuthContext | undefined = undefined>(options: CreateSafeServerActionOptions<TInput, AC> & {
+    input: TInput;
+}, handler: SafeServerActionHandler<TOutput, TInput, AC>): CreateSafeServerActionReturnType<TInput, TOutput, SafeServerActionError>;
+
+export { AuthContext, Awaitable, type CreateSafeRouteHandlerOptions, type CreateSafeRouteHandlerReturnType, type CreateSafeServerActionOptions, type CreateSafeServerActionReturnType, type InferServerActionProvidedInput, type OnValidationErrorResponse, type ProvidedRouteContext, type RouteHandlerAuthFunction, type RouteHandlerAuthFunctionParams, type SafeRouteHandler, type SafeRouteHandlerContext, type SafeServerActionContext, type SafeServerActionError, type SafeServerActionHandler, type SafeServerActionResult, type SafeServerActionResultError, type SafeServerActionResultSuccess, type ServerActionAuthFunction, type ServerActionAuthFunctionParams, type ServerActionErrorContext, type ServerError, type TBodySchema, type TFormDataDict, type TSearchParamsDict, type TSegmentsDict, type UnauthorizedError, type ValidationError, createSafeRouteHandler, createSafeServerAction };