@arkyn/server 3.0.1-beta.142 → 3.0.1-beta.144

package/dist/utilities/errorHandler.js

@@ -13,49 +13,24 @@ import { NoContent } from "../http/successResponses/noContent";
 import { Success } from "../http/successResponses/success";
 import { Updated } from "../http/successResponses/updated";
 /**
- * Handles errors and success responses, converting them into standard HTTP Response objects.
+ * Converts any thrown value into a `Response`. Recognizes all `@arkyn/server` success and error
+ * response classes, native `Response` objects, and falls back to a 500 `ServerError` for anything else.
  *
- * This function acts as a centralized error and response handler that processes various
- * response types (both success and error responses) and converts them into HTTP Response
- * objects. If the error is not recognized, it defaults to returning a ServerError response.
+ * Intended to be used as the catch handler of a route action or loader:
  *
- * @param {any} error - The error or response object to be handled. Can be:
- *   - A native Response object
- *   - A success response instance (Found, Created, Updated, Success, NoContent)
- *   - An error response instance (BadGateway, BadRequest, Conflict, Forbidden, NotFound, NotImplemented, ServerError, Unauthorized, UnprocessableEntity)
- *   - Any other error object (will be wrapped in ServerError)
- *
- * @returns {Response} A standard HTTP Response object with appropriate status code, headers, and body
- *
- * @example
- * ```typescript
- * // Handling a success response
- * try {
- *   const result = await someOperation();
- *   throw new Success("Operation successful", result);
- * } catch (error) {
- *   return errorHandler(error);
- * }
- * ```
- *
- * @example
- * ```typescript
- * // Handling an error response
- * try {
- *   const user = await findUser(id);
- *   if (!user) throw new NotFound("User not found");
- * } catch (error) {
- *   return errorHandler(error);
- * }
- * ```
+ * @param error - The thrown value to convert.
+ * @returns A `Response` with the appropriate HTTP status, headers, and JSON body.
  *
  * @example
  * ```typescript
- * // Handling unexpected errors
- * try {
- *   await riskyOperation();
- * } catch (error) {
- *   return errorHandler(error); // Returns ServerError response
+ * export async function action({ request }: ActionFunctionArgs) {
+ *   try {
+ *     const user = await findUser(id);
+ *     if (!user) throw new NotFound("User not found");
+ *     return new Success("User retrieved", { user }).toJson();
+ *   } catch (error) {
+ *     return errorHandler(error);
+ *   }
  * }
  * ```
  */

package/dist/utilities/flushDebugLogs.d.ts

@@ -1,39 +1,17 @@
 /**
- * Flushes debug logs to the console with colored output in development mode.
+ * Writes colored `[name] message` lines to the console, but only when
+ * `NODE_ENV === "development"` or `DEBUG_MODE === "true"`. No-op in production.
  *
- * This function only outputs logs when running in development mode or when
- * the DEBUG_MODE environment variable is set to "true".
- * Each log entry is prefixed with a colored name tag based on the specified color scheme.
- *
- * @param {object} props - Configuration object for debug logging.
- * @param {string} props.name - The name/label to display before each log entry (e.g., "API", "Database").
- * @param {"yellow" | "cyan" | "red" | "green"} props.scheme - The color scheme for the name tag:
- *   - "yellow": Warning-level logs
- *   - "cyan": Info-level logs
- *   - "red": Error-level logs
- *   - "green": Success-level logs
- * @param {string[]} props.debugs - Array of debug messages to be logged.
- *
- * @returns {void}
+ * @param props.name - Label shown before each line (e.g. `"API"`, `"Auth"`).
+ * @param props.scheme - Color of the label tag: `"cyan"` info, `"green"` success, `"yellow"` warning, `"red"` error.
+ * @param props.debugs - Lines of text to print, one per console entry.
  *
  * @example
  * ```typescript
- * // Log API request information
  * flushDebugLogs({
  *   name: "API",
  *   scheme: "cyan",
- *   debugs: ["POST /api/users", "Status: 201", "Response time: 45ms"]
- * });
- * // Output:
- * // [API] POST /api/users
- * // [API] Status: 201
- * // [API] Response time: 45ms
- *
- * // Log error messages
- * flushDebugLogs({
- *   name: "ERROR",
- *   scheme: "red",
- *   debugs: ["Database connection failed", "Retrying in 5s..."]
+ *   debugs: ["POST /api/users", "Status: 201"],
  * });
  * ```
  */

package/dist/utilities/flushDebugLogs.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"flushDebugLogs.d.ts","sourceRoot":"","sources":["../../src/utilities/flushDebugLogs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAsCG;AAEH,iBAAS,cAAc,CAAC,KAAK,EAAE;IAC7B,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,IAAI,CAyBP;AAED,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"flushDebugLogs.d.ts","sourceRoot":"","sources":["../../src/utilities/flushDebugLogs.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAEH,iBAAS,cAAc,CAAC,KAAK,EAAE;IAC7B,MAAM,EAAE,QAAQ,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,CAAC;IAC5C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,EAAE,CAAC;CAClB,GAAG,IAAI,CAyBP;AAED,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/utilities/flushDebugLogs.js

@@ -1,39 +1,17 @@
 /**
- * Flushes debug logs to the console with colored output in development mode.
+ * Writes colored `[name] message` lines to the console, but only when
+ * `NODE_ENV === "development"` or `DEBUG_MODE === "true"`. No-op in production.
  *
- * This function only outputs logs when running in development mode or when
- * the DEBUG_MODE environment variable is set to "true".
- * Each log entry is prefixed with a colored name tag based on the specified color scheme.
- *
- * @param {object} props - Configuration object for debug logging.
- * @param {string} props.name - The name/label to display before each log entry (e.g., "API", "Database").
- * @param {"yellow" | "cyan" | "red" | "green"} props.scheme - The color scheme for the name tag:
- *   - "yellow": Warning-level logs
- *   - "cyan": Info-level logs
- *   - "red": Error-level logs
- *   - "green": Success-level logs
- * @param {string[]} props.debugs - Array of debug messages to be logged.
- *
- * @returns {void}
+ * @param props.name - Label shown before each line (e.g. `"API"`, `"Auth"`).
+ * @param props.scheme - Color of the label tag: `"cyan"` info, `"green"` success, `"yellow"` warning, `"red"` error.
+ * @param props.debugs - Lines of text to print, one per console entry.
  *
  * @example
  * ```typescript
- * // Log API request information
  * flushDebugLogs({
  *   name: "API",
  *   scheme: "cyan",
- *   debugs: ["POST /api/users", "Status: 201", "Response time: 45ms"]
- * });
- * // Output:
- * // [API] POST /api/users
- * // [API] Status: 201
- * // [API] Response time: 45ms
- *
- * // Log error messages
- * flushDebugLogs({
- *   name: "ERROR",
- *   scheme: "red",
- *   debugs: ["Database connection failed", "Retrying in 5s..."]
+ *   debugs: ["POST /api/users", "Status: 201"],
  * });
  * ```
  */

package/dist/utilities/formAsyncParse.d.ts

@@ -17,40 +17,19 @@ type FormParseProps = [formData: {
 }, schema: ZodType];
 type FormParseReturnType<T extends FormParseProps> = SuccessResponse<T> | ErrorResponse;
 /**
- * Asynchronously parses form data using a Zod schema and returns the result.
+ * Async variant of `formParse` — uses `safeParseAsync` to support Zod schemas with async refinements.
+ * Returns `{ success: true, data }` on success or `{ success: false, fieldErrors, fields }` on failure.
  *
- * @template T - A type that extends `FormParseProps`.
- *
- * @param {T} props - An array containing the form data and the Zod schema.
- * @param {T[0]} formData[0] - The form data to be validated.
- * @param {T[1]} schema[1] - The Zod schema used for validation.
- *
- * @returns {Promise<FormParseReturnType<T>>} A promise that resolves to an object containing the validation result.
- * - If validation fails, it includes:
- *   - `success`: A boolean indicating the validation status (false).
- *   - `fieldErrors`: An object mapping field names to their respective error messages.
- *   - `fields`: The original form data.
- * - If validation succeeds, it includes:
- *   - `success`: A boolean indicating the validation status (true).
- *   - `data`: The parsed and validated data.
+ * @param formData - The raw form data object to validate.
+ * @param schema - The Zod schema to validate against.
  *
  * @example
  * ```typescript
- * import { z } from "zod";
- *
- * const schema = z.object({
- *   name: z.string().min(1, "Name is required"),
- *   age: z.number().min(18, "Must be at least 18"),
- * });
- *
- * const formData = { name: "", age: 17 };
- *
- * const result = await formAsyncParse([formData, schema]);
+ * const schema = z.object({ email: z.string().email() });
+ * const result = await formAsyncParse([{ email: "bad" }, schema]);
  *
  * if (!result.success) {
- *   console.log(result.fieldErrors); // { name: "Name is required", age: "Must be at least 18" }
- * } else {
- *   console.log(result.data); // Parsed data
+ *   console.log(result.fieldErrors); // { email: "Invalid email" }
  * }
  * ```
  */

package/dist/utilities/formAsyncParse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formAsyncParse.d.ts","sourceRoot":"","sources":["../../src/utilities/formAsyncParse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,IAAI;IAC/C,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;CACjD,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAChC,WAAW,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACtC,CAAC;AAEF,KAAK,cAAc,GAAG,CAAC,QAAQ,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAExE,KAAK,mBAAmB,CAAC,CAAC,SAAS,cAAc,IAC7C,eAAe,CAAC,CAAC,CAAC,GAClB,aAAa,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,iBAAe,cAAc,CAAC,CAAC,SAAS,cAAc,EAAE,CACtD,QAAQ,EACR,MAAM,EACP,EAAE,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAqBrC;AAED,OAAO,EAAE,cAAc,EAAE,CAAC"}
+{"version":3,"file":"formAsyncParse.d.ts","sourceRoot":"","sources":["../../src/utilities/formAsyncParse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,IAAI;IAC/C,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;CACjD,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAChC,WAAW,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACtC,CAAC;AAEF,KAAK,cAAc,GAAG,CAAC,QAAQ,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAExE,KAAK,mBAAmB,CAAC,CAAC,SAAS,cAAc,IAC7C,eAAe,CAAC,CAAC,CAAC,GAClB,aAAa,CAAC;AAElB;;;;;;;;;;;;;;;;GAgBG;AAEH,iBAAe,cAAc,CAAC,CAAC,SAAS,cAAc,EAAE,CACtD,QAAQ,EACR,MAAM,EACP,EAAE,CAAC,GAAG,OAAO,CAAC,mBAAmB,CAAC,CAAC,CAAC,CAAC,CAqBrC;AAED,OAAO,EAAE,cAAc,EAAE,CAAC"}

package/dist/utilities/formAsyncParse.js

@@ -1,38 +1,17 @@
 /**
- * Asynchronously parses form data using a Zod schema and returns the result.
+ * Async variant of `formParse` — uses `safeParseAsync` to support Zod schemas with async refinements.
+ * Returns `{ success: true, data }` on success or `{ success: false, fieldErrors, fields }` on failure.
  *
- * @template T - A type that extends `FormParseProps`.
- *
- * @param {T} props - An array containing the form data and the Zod schema.
- * @param {T[0]} formData[0] - The form data to be validated.
- * @param {T[1]} schema[1] - The Zod schema used for validation.
- *
- * @returns {Promise<FormParseReturnType<T>>} A promise that resolves to an object containing the validation result.
- * - If validation fails, it includes:
- *   - `success`: A boolean indicating the validation status (false).
- *   - `fieldErrors`: An object mapping field names to their respective error messages.
- *   - `fields`: The original form data.
- * - If validation succeeds, it includes:
- *   - `success`: A boolean indicating the validation status (true).
- *   - `data`: The parsed and validated data.
+ * @param formData - The raw form data object to validate.
+ * @param schema - The Zod schema to validate against.
  *
  * @example
  * ```typescript
- * import { z } from "zod";
- *
- * const schema = z.object({
- *   name: z.string().min(1, "Name is required"),
- *   age: z.number().min(18, "Must be at least 18"),
- * });
- *
- * const formData = { name: "", age: 17 };
- *
- * const result = await formAsyncParse([formData, schema]);
+ * const schema = z.object({ email: z.string().email() });
+ * const result = await formAsyncParse([{ email: "bad" }, schema]);
  *
  * if (!result.success) {
- *   console.log(result.fieldErrors); // { name: "Name is required", age: "Must be at least 18" }
- * } else {
- *   console.log(result.data); // Parsed data
+ *   console.log(result.fieldErrors); // { email: "Invalid email" }
  * }
  * ```
  */

package/dist/utilities/formParse.d.ts

@@ -17,40 +17,19 @@ type FormParseProps = [formData: {
 }, schema: ZodType];
 type FormParseReturnType<T extends FormParseProps> = SuccessResponse<T> | ErrorResponse;
 /**
- * Parses form data using a Zod schema and returns the result.
+ * Validates form data against a Zod schema synchronously.
+ * Returns `{ success: true, data }` on success or `{ success: false, fieldErrors, fields }` on failure.
  *
- * @template T - A type that extends `FormParseProps`.
- *
- * @param {T} props - An array containing the form data and the Zod schema.
- * @param {T[0]} formData[0] - The form data to be validated.
- * @param {T[1]} schema[1] - The Zod schema used for validation.
- *
- * @returns {FormParseReturnType<T>} An object containing the validation result.
- * - If validation fails, it includes:
- *   - `success`: A boolean indicating the validation status (false).
- *   - `fieldErrors`: An object mapping field names to their respective error messages.
- *   - `fields`: The original form data.
- * - If validation succeeds, it includes:
- *   - `success`: A boolean indicating the validation status (true).
- *   - `data`: The parsed and validated data.
+ * @param formData - The raw form data object to validate.
+ * @param schema - The Zod schema to validate against.
  *
  * @example
  * ```typescript
- * import { z } from "zod";
- *
- * const schema = z.object({
- *   name: z.string().min(1, "Name is required"),
- *   age: z.number().min(18, "Must be at least 18"),
- * });
- *
- * const formData = { name: "", age: 17 };
- *
- * const result = formParse([formData, schema]);
+ * const schema = z.object({ name: z.string().min(1, "Required"), age: z.number().min(18) });
+ * const result = formParse([{ name: "", age: 15 }, schema]);
  *
  * if (!result.success) {
- *   console.log(result.fieldErrors); // { name: "Name is required", age: "Must be at least 18" }
- * } else {
- *   console.log(result.data); // Parsed data
+ *   console.log(result.fieldErrors); // { name: "Required", age: "..." }
  * }
  * ```
  */

package/dist/utilities/formParse.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"formParse.d.ts","sourceRoot":"","sources":["../../src/utilities/formParse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,IAAI;IAC/C,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;CACjD,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAChC,WAAW,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACtC,CAAC;AAEF,KAAK,cAAc,GAAG,CAAC,QAAQ,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAExE,KAAK,mBAAmB,CAAC,CAAC,SAAS,cAAc,IAC7C,eAAe,CAAC,CAAC,CAAC,GAClB,aAAa,CAAC;AAElB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAqCG;AAEH,iBAAS,SAAS,CAAC,CAAC,SAAS,cAAc,EAAE,CAC3C,QAAQ,EACR,MAAM,EACP,EAAE,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAqB5B;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}
+{"version":3,"file":"formParse.d.ts","sourceRoot":"","sources":["../../src/utilities/formParse.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;AAEnC,KAAK,eAAe,CAAC,CAAC,SAAS,cAAc,IAAI;IAC/C,OAAO,EAAE,IAAI,CAAC;IACd,IAAI,EAAE,CAAC,CAAC,CAAC,CAAC,SAAS,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,CAAC,GAAG,KAAK,CAAC;CACjD,CAAC;AAEF,KAAK,aAAa,GAAG;IACnB,OAAO,EAAE,KAAK,CAAC;IACf,MAAM,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;IAChC,WAAW,EAAE;QAAE,CAAC,CAAC,EAAE,MAAM,GAAG,MAAM,CAAA;KAAE,CAAC;CACtC,CAAC;AAEF,KAAK,cAAc,GAAG,CAAC,QAAQ,EAAE;IAAE,CAAC,CAAC,EAAE,MAAM,GAAG,GAAG,CAAA;CAAE,EAAE,MAAM,EAAE,OAAO,CAAC,CAAC;AAExE,KAAK,mBAAmB,CAAC,CAAC,SAAS,cAAc,IAC7C,eAAe,CAAC,CAAC,CAAC,GAClB,aAAa,CAAC;AAElB;;;;;;;;;;;;;;;;GAgBG;AAEH,iBAAS,SAAS,CAAC,CAAC,SAAS,cAAc,EAAE,CAC3C,QAAQ,EACR,MAAM,EACP,EAAE,CAAC,GAAG,mBAAmB,CAAC,CAAC,CAAC,CAqB5B;AAED,OAAO,EAAE,SAAS,EAAE,CAAC"}

package/dist/utilities/formParse.js

@@ -1,38 +1,17 @@
 /**
- * Parses form data using a Zod schema and returns the result.
+ * Validates form data against a Zod schema synchronously.
+ * Returns `{ success: true, data }` on success or `{ success: false, fieldErrors, fields }` on failure.
  *
- * @template T - A type that extends `FormParseProps`.
- *
- * @param {T} props - An array containing the form data and the Zod schema.
- * @param {T[0]} formData[0] - The form data to be validated.
- * @param {T[1]} schema[1] - The Zod schema used for validation.
- *
- * @returns {FormParseReturnType<T>} An object containing the validation result.
- * - If validation fails, it includes:
- *   - `success`: A boolean indicating the validation status (false).
- *   - `fieldErrors`: An object mapping field names to their respective error messages.
- *   - `fields`: The original form data.
- * - If validation succeeds, it includes:
- *   - `success`: A boolean indicating the validation status (true).
- *   - `data`: The parsed and validated data.
+ * @param formData - The raw form data object to validate.
+ * @param schema - The Zod schema to validate against.
  *
  * @example
  * ```typescript
- * import { z } from "zod";
- *
- * const schema = z.object({
- *   name: z.string().min(1, "Name is required"),
- *   age: z.number().min(18, "Must be at least 18"),
- * });
- *
- * const formData = { name: "", age: 17 };
- *
- * const result = formParse([formData, schema]);
+ * const schema = z.object({ name: z.string().min(1, "Required"), age: z.number().min(18) });
+ * const result = formParse([{ name: "", age: 15 }, schema]);
  *
  * if (!result.success) {
- *   console.log(result.fieldErrors); // { name: "Name is required", age: "Must be at least 18" }
- * } else {
- *   console.log(result.data); // Parsed data
+ *   console.log(result.fieldErrors); // { name: "Required", age: "..." }
  * }
  * ```
  */

package/dist/utilities/getScopedParams.d.ts

@@ -1,26 +1,18 @@
 /**
- * Extracts and returns scoped query parameters from a request URL.
+ * Extracts URL search parameters from a request, optionally filtered by a namespace prefix
+ * (e.g. `scope:key` → `key`). Without a scope, returns all search params as-is.
  *
- * @param {Request} request - The incoming request object containing the URL.
- * @param {string} scope - An optional string representing the scope prefix for filtering query parameters.
- *                If no scope is provided, all query parameters are returned.
- *
- * @returns A `URLSearchParams` object containing the scoped query parameters.
- *          If a scope is provided, only parameters with keys starting with the scope
- *          (e.g., `scope:key`) are included, and the scope prefix is removed from the keys.
- *          If no scope is provided, all query parameters are returned as-is.
- *
- * @example
- * // Example 1: No scope provided
- * const request = { url: "https://example.com?key1=value1&key2=value2" };
- * const params = getScopedParams(request);
- * console.log(params.toString()); // Output: "key1=value1&key2=value2"
+ * @param request - The incoming request whose URL will be parsed.
+ * @param scope - Namespace prefix to filter by (e.g. `"table"` matches `table:page`, `table:sort`).
+ * @returns A `URLSearchParams` object with the matching params, stripped of the scope prefix.
  *
  * @example
- * // Example 2: Scope provided
- * const request = { url: "https://example.com?scope:key1=value1&scope:key2=value2&key3=value3" };
- * const params = getScopedParams(request, "scope");
- * console.log(params.toString()); // Output: "key1=value1&key2=value2"
+ * ```typescript
+ * // URL: /products?table:page=2&table:sort=asc&other=1
+ * const params = getScopedParams(request, "table");
+ * params.get("page");  // "2"
+ * params.get("sort");  // "asc"
+ * ```
  */
 declare function getScopedParams(request: Request, scope?: string): URLSearchParams;
 export { getScopedParams };

package/dist/utilities/getScopedParams.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"getScopedParams.d.ts","sourceRoot":"","sources":["../../src/utilities/getScopedParams.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AAEH,iBAAS,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,GAAE,MAAW,mBAW5D;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"getScopedParams.d.ts","sourceRoot":"","sources":["../../src/utilities/getScopedParams.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,iBAAS,eAAe,CAAC,OAAO,EAAE,OAAO,EAAE,KAAK,GAAE,MAAW,mBAW5D;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}

package/dist/utilities/getScopedParams.js

@@ -1,26 +1,18 @@
 /**
- * Extracts and returns scoped query parameters from a request URL.
+ * Extracts URL search parameters from a request, optionally filtered by a namespace prefix
+ * (e.g. `scope:key` → `key`). Without a scope, returns all search params as-is.
  *
- * @param {Request} request - The incoming request object containing the URL.
- * @param {string} scope - An optional string representing the scope prefix for filtering query parameters.
- *                If no scope is provided, all query parameters are returned.
- *
- * @returns A `URLSearchParams` object containing the scoped query parameters.
- *          If a scope is provided, only parameters with keys starting with the scope
- *          (e.g., `scope:key`) are included, and the scope prefix is removed from the keys.
- *          If no scope is provided, all query parameters are returned as-is.
- *
- * @example
- * // Example 1: No scope provided
- * const request = { url: "https://example.com?key1=value1&key2=value2" };
- * const params = getScopedParams(request);
- * console.log(params.toString()); // Output: "key1=value1&key2=value2"
+ * @param request - The incoming request whose URL will be parsed.
+ * @param scope - Namespace prefix to filter by (e.g. `"table"` matches `table:page`, `table:sort`).
+ * @returns A `URLSearchParams` object with the matching params, stripped of the scope prefix.
  *
  * @example
- * // Example 2: Scope provided
- * const request = { url: "https://example.com?scope:key1=value1&scope:key2=value2&key3=value3" };
- * const params = getScopedParams(request, "scope");
- * console.log(params.toString()); // Output: "key1=value1&key2=value2"
+ * ```typescript
+ * // URL: /products?table:page=2&table:sort=asc&other=1
+ * const params = getScopedParams(request, "table");
+ * params.get("page");  // "2"
+ * params.get("sort");  // "asc"
+ * ```
  */
 function getScopedParams(request, scope = "") {
     const url = new URL(request.url);

package/dist/utilities/schemaValidator.d.ts

@@ -1,143 +1,72 @@
 import type { ZodType, z } from "zod";
 /**
- * A schema validator class that provides multiple validation methods for Zod schemas.
+ * Wraps a Zod schema with convenience validation methods suited for server-side use:
+ * - `isValid` — boolean check, no throws
+ * - `safeValidate` — raw Zod result, no throws
+ * - `validate` — throws `ServerError` on failure (for trusted/internal data)
+ * - `formValidate` / `formAsyncValidate` — throws `UnprocessableEntity` on failure (for user-submitted forms)
  *
  * @example
  * ```typescript
- * import { z } from "zod";
+ * const validator = new SchemaValidator(z.object({ email: z.string().email() }));
  *
- * const userSchema = z.object({
- *   name: z.string().min(1, "Name is required"),
- *   email: z.string().email("Invalid email"),
- *   age: z.number().min(18, "Must be at least 18")
- * });
- *
- * const validator = new SchemaValidator(userSchema);
- *
- * // Check if data is valid without throwing
- * const isValid = validator.isValid({ name: "John", email: "john@example.com", age: 25 });
- *
- * // Validate and throw ServerError on failure
- * try {
- *   const validData = validator.validate({ name: "John", email: "john@example.com", age: 25 });
- * } catch (error) {
- *   console.error(error.message);
- * }
- *
- * // Form validation with UnprocessableEntity error
- * try {
- *   const formData = validator.formValidate(requestBody);
- * } catch (error) {
- *   // Returns structured error with fieldErrors for forms
- * }
+ * // Inside a Remix action:
+ * const body = validator.formValidate(await decodeRequestBody(request));
  * ```
  */
 declare class SchemaValidator<T extends ZodType> {
     readonly schema: T;
     /**
-     * Creates a new SchemaValidator instance.
-     * @param {T} schema - The Zod schema to use for validation.
+     * @param schema - The Zod schema used for all validation methods on this instance.
      */
     constructor(schema: T);
     /**
-     * Checks if the provided data is valid according to the schema without throwing errors.
-     *
-     * @param {any} data - The data to validate.
-     *
-     * @returns {boolean} True if the data is valid, false otherwise.
+     * Returns `true` if the data satisfies the schema, `false` otherwise. Never throws.
      *
-     * @example
-     * ```typescript
-     * const validator = new SchemaValidator(userSchema);
-     * const isValid = validator.isValid({ name: "John", email: "invalid-email" });
-     * console.log(isValid); // false
-     * ```
+     * @param data - The value to check.
      */
     isValid(data: any): boolean;
     /**
-     * Safely validates data and returns the complete parse result without throwing errors.
+     * Validates data and returns the raw Zod `safeParseResult` without throwing.
+     * Useful when you need access to the full error details.
      *
-     * @param {any} data - The data to validate.
-     * @returns {z.ZodSafeParseResult<z.infer<T>>} The Zod safe parse result containing success status and data or error.
-     *
-     * @example
-     * ```typescript
-     * const validator = new SchemaValidator(userSchema);
-     * const result = validator.safeValidate({ name: "", email: "john@example.com" });
-     *
-     * if (result.success) {
-     *   console.log(result.data); // Validated data
-     * } else {
-     *   console.log(result.error.issues); // Validation errors
-     * }
-     * ```
+     * @param data - The value to validate.
      */
     safeValidate(data: any): z.ZodSafeParseResult<z.infer<T>>;
     /**
-     * Validates data and returns the parsed result, throwing a ServerError on validation failure.
-     *
-     * @param {any} data - The data to validate.
-     * @throws {ServerError} When validation fails, with a formatted error message.
-     * @returns {z.infer<T>} The validated and parsed data.
-     *
-     * @example
-     * ```typescript
-     * const validator = new SchemaValidator(userSchema);
+     * Validates data and returns the typed result, throwing `ServerError` on failure.
+     * Use for validating internal/trusted data (e.g. env vars, config objects).
      *
-     * try {
-     *   const validUser = validator.validate({ name: "John", email: "john@example.com", age: 25 });
-     *   console.log(validUser); // { name: "John", email: "john@example.com", age: 25 }
-     * } catch (error) {
-     *   console.error(error.message); // "Error validating:\n-> name: String must contain at least 1 character(s)"
-     * }
-     * ```
+     * @param data - The value to validate.
+     * @throws `ServerError` with a formatted field-by-field error message.
      */
     validate(data: any): z.infer<T>;
     /**
-     * Validates form data and returns the parsed result, throwing an UnprocessableEntity error on validation failure.
-     * This method is specifically designed for form validation in web applications.
+     * Validates form data and returns the typed result, throwing `UnprocessableEntity` on failure.
+     * The error includes `fieldErrors`, `fields`, and `data.scrollTo` (first failing field name).
      *
-     * @param {any} data - The form data to validate.
-     * @param {string} [message] - Optional custom error message.
-     * @throws {UnprocessableEntity} When validation fails, with structured field errors for form handling.
-     * @returns {z.infer<T>} The validated and parsed form data.
+     * @param data - The raw form data to validate.
+     * @param message - Optional human-readable error message for the 422 response.
+     * @throws `UnprocessableEntity` with structured field errors for client-side form handling.
      *
      * @example
      * ```typescript
-     * const validator = new SchemaValidator(userSchema);
-     *
-     * try {
-     *   const validFormData = validator.formValidate(requestBody, "User data is invalid");
-     *   console.log(validFormData);
-     * } catch (error) {
-     *   // UnprocessableEntity with fieldErrors, fields, and scrollTo data
-     *   console.log(error.fieldErrors); // { name: "Name is required", email: "Invalid email" }
-     *   console.log(error.data.scrollTo); // "name" (first error field)
-     * }
+     * const validator = new SchemaValidator(registerSchema);
+     * const body = validator.formValidate(await decodeRequestBody(request));
      * ```
      */
     formValidate(data: any, message?: string): z.infer<T>;
     /**
-     * Asynchronously validates form data and returns the parsed result, throwing an UnprocessableEntity error on validation failure.
-     * This method is the async version of formValidate, designed for form validation with async schemas.
+     * Async version of `formValidate` for schemas with async refinements (e.g. uniqueness checks).
      *
-     * @param {any} data - The form data to validate.
-     * @param {string} [message] - Optional custom error message.
-     * @throws {UnprocessableEntity} When validation fails, with structured field errors for form handling.
-     * @returns {Promise<z.infer<T>>} A promise that resolves to the validated and parsed form data.
+     * @param data - The raw form data to validate.
+     * @param message - Optional human-readable error message for the 422 response.
+     * @throws `UnprocessableEntity` with structured field errors for client-side form handling.
      *
      * @example
      * ```typescript
-     * const validator = new SchemaValidator(userSchemaWithAsyncValidation);
-     *
-     * try {
-     *   const validFormData = await validator.formAsyncValidate(requestBody, "User data is invalid");
-     *   console.log(validFormData);
-     * } catch (error) {
-     *   // UnprocessableEntity with fieldErrors, fields, and scrollTo data
-     *   console.log(error.fieldErrors); // { name: "Name is required", email: "Invalid email" }
-     *   console.log(error.data.scrollTo); // "name" (first error field)
-     * }
+     * const validator = new SchemaValidator(registerSchema);
+     * const body = await validator.formAsyncValidate(await decodeRequestBody(request));
      * ```
      */
     formAsyncValidate(data: any, message?: string): Promise<z.infer<T>>;

package/dist/utilities/schemaValidator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"schemaValidator.d.ts","sourceRoot":"","sources":["../../src/utilities/schemaValidator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgBtC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,cAAM,eAAe,CAAC,CAAC,SAAS,OAAO;IAKzB,QAAQ,CAAC,MAAM,EAAE,CAAC;IAJ9B;;;OAGG;gBACkB,MAAM,EAAE,CAAC;IAE9B;;;;;;;;;;;;;OAaG;IACH,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO;IAI3B;;;;;;;;;;;;;;;;;OAiBG;IACH,YAAY,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAIzD;;;;;;;;;;;;;;;;;;OAkBG;IACH,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAQ/B;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACH,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAiBrD;;;;;;;;;;;;;;;;;;;;;;OAsBG;IACG,iBAAiB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;CAgB1E;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}
+{"version":3,"file":"schemaValidator.d.ts","sourceRoot":"","sources":["../../src/utilities/schemaValidator.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAgBtC;;;;;;;;;;;;;;GAcG;AACH,cAAM,eAAe,CAAC,CAAC,SAAS,OAAO;IAIzB,QAAQ,CAAC,MAAM,EAAE,CAAC;IAH9B;;OAEG;gBACkB,MAAM,EAAE,CAAC;IAE9B;;;;OAIG;IACH,OAAO,CAAC,IAAI,EAAE,GAAG,GAAG,OAAO;IAI3B;;;;;OAKG;IACH,YAAY,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC,kBAAkB,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IAIzD;;;;;;OAMG;IACH,QAAQ,CAAC,IAAI,EAAE,GAAG,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAQ/B;;;;;;;;;;;;;OAaG;IACH,YAAY,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC;IAiBrD;;;;;;;;;;;;OAYG;IACG,iBAAiB,CAAC,IAAI,EAAE,GAAG,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;CAgB1E;AAED,OAAO,EAAE,eAAe,EAAE,CAAC"}