@mpen/routekit 0.1.0 → 0.1.1

package/dist/responses-B379Ep9Y.d.mts

@@ -0,0 +1,296 @@
+import { n as RoutekitResponse, r as RoutekitResponseInit } from "./core-CzUCxvGk.mjs";
+import { HttpStatus } from "@mpen/http";
+
+//#region src/router/response/formats/problem/types.d.ts
+/**
+ * Path segment used to locate a validation or business-rule issue.
+ *
+ * @example
+ * ```ts
+ * const path: ProblemIssuePathSegment[] = ['body', 'users', 0, 'email']
+ * ```
+ */
+type ProblemIssuePathSegment = string | number;
+/**
+ * A single issue associated with a problem response.
+ *
+ * @example
+ * ```ts
+ * const issue: ProblemIssue<'required'> = {
+ *     code: 'required',
+ *     message: 'Email is required',
+ *     path: ['body', 'email'],
+ * }
+ * ```
+ *
+ * @typeParam Code - Machine-readable issue code.
+ */
+interface ProblemIssue<Code extends string = string> {
+  /**
+   * Machine-readable issue code.
+   */
+  code: Code;
+  /**
+   * Human-readable issue message.
+   */
+  message: string;
+  /**
+   * Structured path to the invalid value.
+   */
+  path?: readonly ProblemIssuePathSegment[];
+  /**
+   * Expected value description.
+   */
+  expected?: string;
+  /**
+   * Received value description.
+   */
+  received?: string;
+}
+/**
+ * Primary problem metadata that clients can switch on.
+ *
+ * @example
+ * ```ts
+ * const error: ProblemError<'not_found'> = {
+ *     code: 'not_found',
+ *     message: 'No user exists for the provided id.',
+ *     title: 'User not found',
+ * }
+ * ```
+ *
+ * @typeParam Code - Machine-readable error code.
+ */
+interface ProblemError<Code extends string = string> {
+  /**
+   * Machine-readable error code.
+   */
+  code: Code;
+  /**
+   * Human-readable problem message clients can display by default.
+   */
+  message: string;
+  /**
+   * Optional short problem heading.
+   */
+  title?: string;
+}
+/**
+ * Successful standard response envelope.
+ *
+ * @example
+ * ```ts
+ * const response: SuccessResponse<{ id: string }> = {
+ *     success: true,
+ *     data: { id: 'user_123' },
+ * }
+ * ```
+ *
+ * @typeParam Data - Successful response payload type.
+ * @typeParam Meta - Optional metadata payload type.
+ */
+interface SuccessResponse<Data = unknown, Meta = unknown> {
+  /**
+   * Discriminator for successful responses.
+   */
+  success: true;
+  /**
+   * Successful response payload.
+   */
+  data: Data;
+  /**
+   * Optional response metadata.
+   */
+  meta?: Meta;
+}
+/**
+ * Error standard response envelope.
+ *
+ * @example
+ * ```ts
+ * const response: ProblemResponse<'validation_failed'> = {
+ *     success: false,
+ *     error: {
+ *         code: 'validation_failed',
+ *         message: 'Validation failed',
+ *     },
+ *     issues: [{ code: 'required', message: 'Email is required', path: ['body', 'email'] }],
+ * }
+ * ```
+ *
+ * @typeParam Code - Machine-readable primary error code.
+ * @typeParam Issue - Issue shape used for validation or business-rule details.
+ */
+interface ProblemResponse<Code extends string = string, Issue extends ProblemIssue = ProblemIssue> {
+  /**
+   * Discriminator for problem responses.
+   */
+  success: false;
+  /**
+   * Primary error clients can switch on.
+   */
+  error: ProblemError<Code>;
+  /**
+   * Optional validation or business-rule issues.
+   */
+  issues?: readonly Issue[];
+}
+/**
+ * Standard response union for successful and problem responses.
+ *
+ * @example
+ * ```ts
+ * type GetUserResponse = StandardResponse<{ id: string }, 'not_found'>
+ * ```
+ *
+ * @typeParam Data - Successful response payload type.
+ * @typeParam Code - Machine-readable primary error code.
+ * @typeParam Issue - Issue shape used for validation or business-rule details.
+ * @typeParam Meta - Optional metadata payload type.
+ */
+type StandardResponse<Data = unknown, Code extends string = string, Issue extends ProblemIssue = ProblemIssue, Meta = unknown> = SuccessResponse<Data, Meta> | ProblemResponse<Code, Issue>;
+//#endregion
+//#region src/router/response/formats/problem/responses.d.ts
+/**
+ * Default primary error code for validation problem responses.
+ *
+ * @example
+ * ```ts
+ * validationProblem([{ code: 'required', message: 'Name is required' }])
+ * ```
+ */
+declare const VALIDATION_PROBLEM_CODE = "validation_failed";
+/**
+ * Options accepted by [`ok`]{@link ok}.
+ *
+ * @example
+ * ```ts
+ * ok({ id: 'user_123' }, { meta: { requestId: 'req_123' } })
+ * ```
+ *
+ * @typeParam Meta - Optional metadata payload type.
+ */
+interface SuccessResponseInit<Meta = unknown> extends Omit<RoutekitResponseInit, 'status'> {
+  /**
+   * Optional response metadata.
+   */
+  meta?: Meta;
+}
+/**
+ * Options accepted by [`problem`]{@link problem}.
+ *
+ * @example
+ * ```ts
+ * problem({
+ *     code: 'not_found',
+ *     status: 404,
+ *     message: 'No user exists for the provided id.',
+ *     title: 'User not found',
+ * })
+ * ```
+ *
+ * @typeParam Code - Machine-readable primary error code.
+ * @typeParam Issue - Issue shape used for validation or business-rule details.
+ */
+interface ProblemResponseInit<Code extends string = string, Issue extends ProblemIssue = ProblemIssue, Status extends number = number> extends Omit<RoutekitResponseInit, 'status'> {
+  /**
+   * Machine-readable error code.
+   */
+  code: Code;
+  /**
+   * Human-readable problem message clients can display by default.
+   */
+  message: string;
+  /**
+   * HTTP status code for this response.
+   */
+  status: Status;
+  /**
+   * Optional short problem heading.
+   */
+  title?: string;
+  /**
+   * Optional validation or business-rule issues.
+   */
+  issues?: readonly Issue[];
+}
+/**
+ * Options accepted by [`validationProblem`]{@link validationProblem}.
+ *
+ * @example
+ * ```ts
+ * validationProblem([{ code: 'invalid_type', message: 'Expected a string' }], {
+ *     message: 'The request body was invalid.',
+ * })
+ * ```
+ *
+ * @typeParam Code - Machine-readable primary error code.
+ * @typeParam Issue - Issue shape used for validation details.
+ */
+interface ValidationProblemInit<Code extends string = typeof VALIDATION_PROBLEM_CODE, Issue extends ProblemIssue = ProblemIssue, Status extends number = number> extends Omit<ProblemResponseInit<Code, Issue, Status>, 'code' | 'message' | 'status' | 'issues'> {
+  /**
+   * Machine-readable validation error code.
+   */
+  code?: Code;
+  /**
+   * Human-readable validation summary.
+   */
+  message?: string;
+  /**
+   * HTTP status code for this response. Defaults to `400`.
+   */
+  status?: Status;
+}
+/**
+ * Create a `200 OK` standard response envelope.
+ *
+ * @example
+ * ```ts
+ * router.get('/users/:id', () => ok({ id: 'user_123' }))
+ * ```
+ *
+ * @param data - Successful response payload.
+ * @param init - Response headers and optional metadata.
+ * @returns Routekit logical response with an [`SuccessResponse`]{@link SuccessResponse} body.
+ * @typeParam Data - Successful response payload type.
+ * @typeParam Meta - Optional metadata payload type.
+ */
+declare function ok<const Data, const Meta = unknown>(data: Data, init?: SuccessResponseInit<Meta>): RoutekitResponse<SuccessResponse<Data, Meta>, HttpStatus.OK>;
+/**
+ * Create a standard problem response envelope.
+ *
+ * @example
+ * ```ts
+ * return problem({
+ *     code: 'not_found',
+ *     status: 404,
+ *     message: 'No user exists for the provided id.',
+ *     title: 'User not found',
+ * })
+ * ```
+ *
+ * @param init - Problem response data, headers, and status.
+ * @returns Routekit logical response with a [`ProblemResponse`]{@link ProblemResponse} body.
+ * @typeParam Code - Machine-readable primary error code.
+ * @typeParam Issue - Issue shape used for validation or business-rule details.
+ */
+declare function problem<const Code extends string, const Issue extends ProblemIssue = ProblemIssue, const Status extends number = number>(init: ProblemResponseInit<Code, Issue, Status>): RoutekitResponse<ProblemResponse<Code, Issue>, Status>;
+/**
+ * Create a standard validation problem response envelope.
+ *
+ * @example
+ * ```ts
+ * return validationProblem([
+ *     { code: 'required', message: 'Email is required', path: ['body', 'email'] },
+ * ])
+ * ```
+ *
+ * @param issues - Validation issues to include in the response.
+ * @param init - Optional problem response overrides and headers.
+ * @returns Routekit logical response with a validation [`ProblemResponse`]{@link ProblemResponse}.
+ * @typeParam Issue - Issue shape used for validation details.
+ * @typeParam Code - Machine-readable primary error code.
+ */
+declare function validationProblem<const Issue extends ProblemIssue, const Code extends string = typeof VALIDATION_PROBLEM_CODE, const Status extends number = HttpStatus.BAD_REQUEST>(issues: readonly Issue[], init?: ValidationProblemInit<Code, Issue, Status>): RoutekitResponse<ProblemResponse<Code, Issue>, Status | HttpStatus.BAD_REQUEST>;
+//#endregion
+export { ok as a, ProblemError as c, ProblemResponse as d, StandardResponse as f, ValidationProblemInit as i, ProblemIssue as l, SuccessResponseInit as n, problem as o, SuccessResponse as p, VALIDATION_PROBLEM_CODE as r, validationProblem as s, ProblemResponseInit as t, ProblemIssuePathSegment as u };

package/dist/responses-BpVrgeYi.mjs

@@ -0,0 +1,101 @@
+import { a as response } from "./core-DbmQauwS.mjs";
+import { HttpStatus } from "@mpen/http";
+//#region src/router/response/formats/problem/responses.ts
+/**
+* Default primary error code for validation problem responses.
+*
+* @example
+* ```ts
+* validationProblem([{ code: 'required', message: 'Name is required' }])
+* ```
+*/
+const VALIDATION_PROBLEM_CODE = "validation_failed";
+function withDefinedOptional(value, key, field) {
+	if (field === void 0) return value;
+	return {
+		...value,
+		[key]: field
+	};
+}
+/**
+* Create a `200 OK` standard response envelope.
+*
+* @example
+* ```ts
+* router.get('/users/:id', () => ok({ id: 'user_123' }))
+* ```
+*
+* @param data - Successful response payload.
+* @param init - Response headers and optional metadata.
+* @returns Routekit logical response with an [`SuccessResponse`]{@link SuccessResponse} body.
+* @typeParam Data - Successful response payload type.
+* @typeParam Meta - Optional metadata payload type.
+*/
+function ok(data, init = {}) {
+	const { meta, ...responseInit } = init;
+	return response(withDefinedOptional({
+		success: true,
+		data
+	}, "meta", meta), {
+		...responseInit,
+		status: HttpStatus.OK
+	});
+}
+/**
+* Create a standard problem response envelope.
+*
+* @example
+* ```ts
+* return problem({
+*     code: 'not_found',
+*     status: 404,
+*     message: 'No user exists for the provided id.',
+*     title: 'User not found',
+* })
+* ```
+*
+* @param init - Problem response data, headers, and status.
+* @returns Routekit logical response with a [`ProblemResponse`]{@link ProblemResponse} body.
+* @typeParam Code - Machine-readable primary error code.
+* @typeParam Issue - Issue shape used for validation or business-rule details.
+*/
+function problem(init) {
+	const { code, message, status, title, issues, ...responseInit } = init;
+	return response(withDefinedOptional({
+		success: false,
+		error: withDefinedOptional({
+			code,
+			message
+		}, "title", title)
+	}, "issues", issues), {
+		...responseInit,
+		status
+	});
+}
+/**
+* Create a standard validation problem response envelope.
+*
+* @example
+* ```ts
+* return validationProblem([
+*     { code: 'required', message: 'Email is required', path: ['body', 'email'] },
+* ])
+* ```
+*
+* @param issues - Validation issues to include in the response.
+* @param init - Optional problem response overrides and headers.
+* @returns Routekit logical response with a validation [`ProblemResponse`]{@link ProblemResponse}.
+* @typeParam Issue - Issue shape used for validation details.
+* @typeParam Code - Machine-readable primary error code.
+*/
+function validationProblem(issues, init = {}) {
+	return problem({
+		...init,
+		code: init.code ?? "validation_failed",
+		message: init.message ?? "Validation failed",
+		status: init.status ?? HttpStatus.BAD_REQUEST,
+		issues
+	});
+}
+//#endregion
+export { validationProblem as i, ok as n, problem as r, VALIDATION_PROBLEM_CODE as t };