@xrystal/dto 26.6.27-v12

package/dist/types/builder.d.ts

@@ -0,0 +1,15 @@
+import type { HeaderValue } from './codes.js';
+import type { FinalResult, Payload, SchemaInput } from './response.js';
+/** Minimal builder surface for plugins and attachable contexts — no runtime import from `core`. */
+export interface BuilderRef<T = unknown> {
+    httpStatus(code: number): this;
+    code(code: number): this;
+    status(value: boolean): this;
+    message(msg: string): this;
+    data(data: T | undefined): this;
+    payload(partial: Payload<T>): this;
+    schema(input?: SchemaInput<T>): this;
+    setMeta(meta: Record<string, unknown>): this;
+    header(key: string, value: HeaderValue): this;
+    build(): FinalResult<T> | unknown;
+}

package/dist/types/codes.d.ts

@@ -0,0 +1,7 @@
+export type HeaderValue = string | number | readonly string[];
+export type CodeMap = Record<string, number>;
+/**
+ * Add or override numeric codes at adapter construction.
+ * Keys you omit keep the built-in defaults (SUCCESS: 0, CLIENT: 1, …).
+ */
+export type CodeOverrides = Record<string, number>;

package/dist/types/context.d.ts

@@ -0,0 +1,16 @@
+import type { BuilderRef } from './builder.js';
+export interface RequestContext {
+    requestId: string;
+    startTime: number;
+}
+export interface IncomingHttpRequest {
+    headers?: Record<string, string | string[] | undefined>;
+    get?: (header: string) => string | undefined;
+}
+export interface ContextFactoryOptions {
+    requestIdHeaders?: readonly string[];
+}
+export interface BuilderAttachable<T = unknown> {
+    ctx?: RequestContext;
+    builder?: BuilderRef<T>;
+}

package/dist/types/hooks.d.ts

@@ -0,0 +1,7 @@
+export type HookEvent = 'before_build' | 'after_build' | 'before_dispatch' | 'after_dispatch' | 'error';
+export type HookFn = (payload: unknown) => void;
+export interface HookBus {
+    on(event: HookEvent, fn: HookFn): unknown;
+    hasListeners(event: HookEvent): boolean;
+    emit(event: HookEvent, payload: unknown): void;
+}

package/dist/types/index.d.ts

@@ -0,0 +1,10 @@
+export type { BuilderRef } from './builder.js';
+export type { HeaderValue, CodeMap, CodeOverrides } from './codes.js';
+export type { Payload, PayloadExtras, PaginationMeta, ResponseBody, SchemaInput, Cookie, FinalResult, } from './response.js';
+export type { RequestContext, IncomingHttpRequest, ContextFactoryOptions, BuilderAttachable, } from './context.js';
+export type { BuilderOptions, RuntimeOptions, DTOConfig } from './options.js';
+export type { HookEvent, HookFn, HookBus } from './hooks.js';
+export type { Dispatcher, PluginContext, Plugin } from './plugin.js';
+export { definePlugin, mergePlugins } from './plugin.js';
+export type { LogInput, LogBody, ILogDTO } from './log.js';
+export type { QueueMetadata, QueueMessageInput, QueueMessage, IMetadata, IMessageInput, } from './queue.js';

package/dist/types/log.d.ts

@@ -0,0 +1 @@
+export type { LogInput, LogBody, LogSchemaInput, ILogDTO } from '../dto/log/types.js';

package/dist/types/metadata.d.ts

@@ -0,0 +1,7 @@
+export interface ResponseMeta {
+    requestId: string;
+    serverTime: string;
+    statusCode: number;
+    [key: string]: unknown;
+}
+export type MetadataOptions = Partial<ResponseMeta> & Record<string, unknown>;

package/dist/types/options.d.ts

@@ -0,0 +1,24 @@
+import type { CodeOverrides } from './codes.js';
+import type { HookBus } from './hooks.js';
+export interface BuilderOptions {
+    /** When true, surfaces raw error messages/stacks. Default: false */
+    verbose?: boolean;
+    includeStack?: boolean;
+    withDefaultBody?: boolean;
+    codes?: CodeOverrides;
+    defaultHeaders?: Record<string, string>;
+    hooks?: HookBus;
+    plugins?: import('./plugin.js').Plugin<unknown>[];
+}
+export interface RuntimeOptions extends BuilderOptions {
+    withDefaultHeaders?: boolean;
+    requestIdHeaders?: readonly string[];
+    /** Socket.IO emit event. Prefer `DTOConfig.socket.event` on `new DTO()` */
+    event?: string;
+}
+export interface DTOConfig extends RuntimeOptions {
+    /** Socket.IO emit event name. Default: `response` */
+    socket?: {
+        event?: string;
+    };
+}

package/dist/types/plugin.d.ts

@@ -0,0 +1,35 @@
+import type { BuilderRef } from './builder.js';
+import type { CodeMap } from './codes.js';
+import type { RequestContext } from './context.js';
+import type { BuilderOptions } from './options.js';
+import type { FinalResult } from './response.js';
+export interface Dispatcher<T = unknown> {
+    dispatch(result: FinalResult<T>): FinalResult<T> | unknown;
+}
+export interface PluginContext<T = unknown> {
+    builder: BuilderRef<T>;
+    context?: RequestContext;
+    options: BuilderOptions;
+    codes: CodeMap;
+}
+/**
+ * Response pipeline plugin — middleware-style hooks on the builder lifecycle.
+ *
+ * - `beforeBuild` — mutate the builder before the body is assembled (add meta, headers, …)
+ * - `afterBuild` / `beforeDispatch` — receive `FinalResult`, return a replacement or `void` to pass through
+ * - `afterDispatch` — side effects after the runtime sends (logging, metrics)
+ *
+ * Register on `new DTO()` via constructor `plugins` or `.use(plugin)`.
+ */
+export interface Plugin<T = unknown> {
+    readonly name: string;
+    /** Lower runs first. Default: `0` */
+    readonly priority?: number;
+    beforeBuild?(ctx: PluginContext<T>): void;
+    afterBuild?(result: FinalResult<T>, ctx: PluginContext<T>): FinalResult<T> | void;
+    beforeDispatch?(result: FinalResult<T>, ctx: PluginContext<T>): FinalResult<T> | void;
+    afterDispatch?(result: FinalResult<T>, ctx: PluginContext<T>): void;
+}
+/** Type-safe plugin factory — use when defining reusable plugins. */
+export declare function definePlugin<T = unknown>(plugin: Plugin<T>): Plugin<T>;
+export declare function mergePlugins(...groups: Array<Plugin<unknown>[] | undefined>): Plugin<unknown>[];

package/dist/types/queue.d.ts

@@ -0,0 +1 @@
+export type { QueueMetadata, QueueMessageInput, QueueMessage, QueueSchemaInput, IMetadata, IMessageInput, } from '../dto/queue/types.js';

package/dist/types/response.d.ts

@@ -0,0 +1,43 @@
+import type { HeaderValue } from './codes.js';
+export interface Payload<T = unknown> {
+    data?: T;
+    meta?: Record<string, unknown>;
+    headers?: Record<string, string>;
+    pagination?: PaginationMeta;
+    [key: string]: unknown;
+}
+/** Payload fields except `data` — used as 3rd arg on `.as.ok(data, message, extras)` */
+export type PayloadExtras = Omit<Payload, 'data'>;
+export interface PaginationMeta {
+    total: number;
+    page: number;
+    limit: number;
+    totalPages: number;
+    hasNext: boolean;
+}
+/** Fixed field order: status → message → payload? → code */
+export interface ResponseBody<T = unknown> {
+    status: boolean;
+    message: string;
+    payload?: Payload<T>;
+    code: number;
+}
+/**
+ * Input for `.schema()` on the builder chain — body fields only.
+ * Transport concerns (`.httpStatus()`, headers, cookies) stay on the chain before `.build()`.
+ * Last call wins: `.schema()` overrides prior body setters; later setters override `.schema()`.
+ * When `payload` is set, it replaces the entire payload (no merge with earlier chain calls).
+ * `status`, `message`, and `code` are always present in the output; defaults apply when omitted.
+ */
+export type SchemaInput<T = unknown> = Partial<Pick<ResponseBody<T>, 'status' | 'message' | 'code' | 'payload'>>;
+export interface Cookie {
+    name: string;
+    value: string;
+    options?: Record<string, unknown>;
+}
+export interface FinalResult<T = unknown> {
+    body: ResponseBody<T>;
+    statusCode: number;
+    headers: Record<string, HeaderValue>;
+    cookies: Cookie[];
+}

package/dist/utils/constants/http.d.ts

@@ -0,0 +1,2 @@
+export declare const NO_BODY_STATUS_CODES: Set<number>;
+export declare function shouldSendResponseBody(statusCode: number): boolean;

package/dist/utils/constants/index.d.ts

@@ -0,0 +1,3 @@
+export { StatusCodes, type StatusCodeCategory, type StatusCodeType, } from './status-codes.js';
+export { DEFAULT_SECURITY_HEADERS } from './security-headers.js';
+export { NO_BODY_STATUS_CODES, shouldSendResponseBody } from './http.js';

package/dist/utils/constants/security-headers.d.ts

@@ -0,0 +1 @@
+export declare const DEFAULT_SECURITY_HEADERS: Record<string, string>;

package/dist/utils/constants/status-codes.d.ts

@@ -0,0 +1,35 @@
+export declare const StatusCodes: {
+    readonly SUCCESSFUL: {
+        readonly OK: 200;
+        readonly CREATED: 201;
+        readonly ACCEPTED: 202;
+        readonly NO_CONTENT: 204;
+    };
+    readonly REDIRECTION: {
+        readonly MOVED_PERMANENTLY: 301;
+        readonly FOUND: 302;
+        readonly NOT_MODIFIED: 304;
+    };
+    readonly CLIENT_ERROR: {
+        readonly BAD_REQUEST: 400;
+        readonly UNAUTHORIZED: 401;
+        readonly FORBIDDEN: 403;
+        readonly NOT_FOUND: 404;
+        readonly METHOD_NOT_ALLOWED: 405;
+        readonly CONFLICT: 409;
+        readonly GONE: 410;
+        readonly PAYLOAD_TOO_LARGE: 413;
+        readonly UNSUPPORTED_MEDIA_TYPE: 415;
+        readonly UNPROCESSABLE_ENTITY: 422;
+        readonly TOO_MANY_REQUESTS: 429;
+    };
+    readonly SERVER_ERROR: {
+        readonly INTERNAL_SERVER_ERROR: 500;
+        readonly NOT_IMPLEMENTED: 501;
+        readonly BAD_GATEWAY: 502;
+        readonly SERVICE_UNAVAILABLE: 503;
+        readonly GATEWAY_TIMEOUT: 504;
+    };
+};
+export type StatusCodeCategory = keyof typeof StatusCodes;
+export type StatusCodeType = (typeof StatusCodes)[StatusCodeCategory][keyof (typeof StatusCodes)[StatusCodeCategory]];

package/dist/utils/helpers/index.d.ts

@@ -0,0 +1,2 @@
+export { generateUUID, isValidUUID } from './uuid.js';
+export { DEFAULT_REQUEST_ID_HEADERS, resolveRequestId, } from './request-id.js';

package/dist/utils/helpers/request-id.d.ts

@@ -0,0 +1,3 @@
+import type { IncomingHttpRequest } from '../../types/context.js';
+export declare const DEFAULT_REQUEST_ID_HEADERS: readonly ["x-request-id", "x-correlation-id", "traceparent"];
+export declare function resolveRequestId(req: IncomingHttpRequest, headerNames?: readonly string[]): string;

package/dist/utils/helpers/uuid.d.ts

@@ -0,0 +1,2 @@
+export declare function generateUUID(): string;
+export declare function isValidUUID(id: string): boolean;

package/dist/utils/index.d.ts

@@ -0,0 +1,2 @@
+export { StatusCodes, type StatusCodeCategory, type StatusCodeType, DEFAULT_SECURITY_HEADERS, NO_BODY_STATUS_CODES, shouldSendResponseBody, } from './constants/index.js';
+export { generateUUID, isValidUUID, DEFAULT_REQUEST_ID_HEADERS, resolveRequestId, } from './helpers/index.js';

package/package.json

@@ -0,0 +1,130 @@
+{
+  "name": "@xrystal/dto",
+  "version": "26.06.27-v12",
+  "description": "Framework-agnostic Data Transfer Object library for HTTP, WebSocket, and Socket.IO responses, logs, and queue messages.",
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    },
+    "./dto": {
+      "types": "./dist/dto/runtime/dto.d.ts",
+      "import": "./dist/dto/runtime/dto.js",
+      "require": "./dist/dto/runtime/dto.cjs"
+    },
+    "./response": {
+      "types": "./dist/dto/response/index.d.ts",
+      "import": "./dist/dto/response/index.js",
+      "require": "./dist/dto/response/index.cjs"
+    },
+    "./log": {
+      "types": "./dist/dto/log/index.d.ts",
+      "import": "./dist/dto/log/index.js",
+      "require": "./dist/dto/log/index.cjs"
+    },
+    "./queue": {
+      "types": "./dist/dto/queue/index.d.ts",
+      "import": "./dist/dto/queue/index.js",
+      "require": "./dist/dto/queue/index.cjs"
+    },
+    "./core": {
+      "types": "./dist/core/index.d.ts",
+      "import": "./dist/core/index.js",
+      "require": "./dist/core/index.cjs"
+    },
+    "./express": {
+      "types": "./dist/adapters/express.d.ts",
+      "import": "./dist/adapters/express.js",
+      "require": "./dist/adapters/express.cjs"
+    },
+    "./node": {
+      "types": "./dist/adapters/node.d.ts",
+      "import": "./dist/adapters/node.js",
+      "require": "./dist/adapters/node.cjs"
+    },
+    "./elysia": {
+      "types": "./dist/adapters/elysia.d.ts",
+      "import": "./dist/adapters/elysia.js",
+      "require": "./dist/adapters/elysia.cjs"
+    },
+    "./websocket": {
+      "types": "./dist/adapters/websocket.d.ts",
+      "import": "./dist/adapters/websocket.js",
+      "require": "./dist/adapters/websocket.cjs"
+    },
+    "./socketio": {
+      "types": "./dist/adapters/socketio.d.ts",
+      "import": "./dist/adapters/socketio.js",
+      "require": "./dist/adapters/socketio.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "test": "node --experimental-vm-modules node_modules/jest/bin/jest.js",
+    "test:verbose": "node --experimental-vm-modules node_modules/jest/bin/jest.js --verbose",
+    "test:watch": "node --experimental-vm-modules node_modules/jest/bin/jest.js --watch",
+    "build": "node src/utils/scripts/build.mjs",
+    "build:only": "tsup",
+    "build:types": "tsc -p tsconfig.build.json",
+    "build:release": "npm run build:only && npm run build:types",
+    "release": "node src/utils/scripts/release.mjs",
+    "tag": "node src/utils/scripts/tag.mjs",
+    "version:check": "node src/utils/scripts/version-check.mjs",
+    "lint": "tsc --noEmit -p tsconfig.json",
+    "prepublishOnly": "npm run lint && npm run test && npm run build:release"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xdloper/x.git"
+  },
+  "keywords": [
+    "dto",
+    "data-transfer-object",
+    "api",
+    "response",
+    "builder",
+    "middleware",
+    "express",
+    "elysia",
+    "bun",
+    "nodejs",
+    "typescript"
+  ],
+  "author": "xrystal",
+  "license": "MIT",
+  "peerDependencies": {
+    "elysia": ">=1.0.0",
+    "express": "^4.0.0 || ^5.0.0"
+  },
+  "peerDependenciesMeta": {
+    "express": {
+      "optional": true
+    },
+    "elysia": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@types/express": "^5.0.6",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^25.6.0",
+    "@types/supertest": "^7.2.0",
+    "elysia": "^1.3.0",
+    "express": "^5.2.1",
+    "jest": "^29.7.0",
+    "supertest": "^7.2.2",
+    "ts-jest": "^29.4.0",
+    "tsup": "^8.5.1",
+    "typescript": "^6.0.3"
+  }
+}