@xrystal/dto 26.6.27-v12

package/dist/dto/queue/index.js

@@ -0,0 +1,151 @@
+// src/dto/queue/assemble.ts
+function assembleQueueMessage(metadata, payload) {
+  const orderedMetadata = {
+    source: metadata.source,
+    eventType: metadata.eventType,
+    timestamp: metadata.timestamp,
+    correlationId: metadata.correlationId
+  };
+  if (metadata.userId !== void 0) {
+    orderedMetadata.userId = metadata.userId;
+  }
+  if (metadata.extraData !== void 0) {
+    orderedMetadata.extraData = metadata.extraData;
+  }
+  return {
+    metadata: orderedMetadata,
+    payload
+  };
+}
+
+// src/utils/helpers/uuid.ts
+function generateUUID() {
+  if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") {
+    return crypto.randomUUID();
+  }
+  const bytes = new Uint8Array(16);
+  if (typeof crypto !== "undefined" && typeof crypto.getRandomValues === "function") {
+    crypto.getRandomValues(bytes);
+  } else {
+    for (let i = 0; i < bytes.length; i++) {
+      bytes[i] = Math.floor(Math.random() * 256);
+    }
+  }
+  bytes[6] = bytes[6] & 15 | 64;
+  bytes[8] = bytes[8] & 63 | 128;
+  const hex = Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("");
+  return `${hex.slice(0, 8)}-${hex.slice(8, 12)}-${hex.slice(12, 16)}-${hex.slice(16, 20)}-${hex.slice(20)}`;
+}
+
+// src/dto/shared/schema-utils.ts
+function assertRequiredFields(input, fields, label = "Missing required fields") {
+  const missing = fields.filter((field) => {
+    const value = input[field];
+    return value === void 0 || value === null || value === "";
+  });
+  if (missing.length > 0) {
+    throw new Error(`${label}: ${missing.join(", ")}`);
+  }
+}
+
+// src/dto/shared/base-dto.ts
+var BaseDTO = class {
+};
+
+// src/dto/queue/builder.ts
+var QueueDTO = class _QueueDTO extends BaseDTO {
+  _source;
+  _eventType;
+  _userId;
+  _correlationId;
+  _extraData;
+  _payload;
+  _timestamp;
+  static source(value) {
+    return new _QueueDTO().source(value);
+  }
+  static eventType(value) {
+    return new _QueueDTO().eventType(value);
+  }
+  static userId(value) {
+    return new _QueueDTO().userId(value);
+  }
+  static correlationId(value) {
+    return new _QueueDTO().correlationId(value);
+  }
+  static extraData(value) {
+    return new _QueueDTO().extraData(value);
+  }
+  static timestamp(value) {
+    return new _QueueDTO().timestamp(value);
+  }
+  static payload(value) {
+    return new _QueueDTO().payload(value);
+  }
+  static schema(input = {}) {
+    return new _QueueDTO().schema(input);
+  }
+  source(value) {
+    this._source = value;
+    return this;
+  }
+  eventType(value) {
+    this._eventType = value;
+    return this;
+  }
+  userId(value) {
+    this._userId = value;
+    return this;
+  }
+  correlationId(value) {
+    this._correlationId = value;
+    return this;
+  }
+  extraData(value) {
+    this._extraData = value;
+    return this;
+  }
+  timestamp(value) {
+    this._timestamp = value;
+    return this;
+  }
+  payload(value) {
+    this._payload = value;
+    return this;
+  }
+  schema(input = {}) {
+    const { metadata, payload } = input;
+    if (metadata?.source !== void 0) this.source(metadata.source);
+    if (metadata?.eventType !== void 0) this.eventType(metadata.eventType);
+    if (metadata?.userId !== void 0) this.userId(metadata.userId);
+    if (metadata?.correlationId !== void 0) this.correlationId(metadata.correlationId);
+    if (metadata?.extraData !== void 0) this.extraData(metadata.extraData);
+    if (payload !== void 0) {
+      this._payload = payload;
+    }
+    return this;
+  }
+  build() {
+    assertRequiredFields(
+      {
+        source: this._source,
+        eventType: this._eventType
+      },
+      ["source", "eventType"],
+      "Missing queue metadata fields"
+    );
+    return assembleQueueMessage(
+      {
+        source: this._source,
+        eventType: this._eventType,
+        timestamp: this._timestamp ?? Date.now(),
+        correlationId: this._correlationId ?? generateUUID(),
+        userId: this._userId,
+        extraData: this._extraData
+      },
+      this._payload
+    );
+  }
+};
+
+export { QueueDTO, assembleQueueMessage };

package/dist/dto/queue/types.d.ts

@@ -0,0 +1,34 @@
+export interface QueueMetadata<E = unknown> {
+    source: string;
+    eventType: string;
+    timestamp: number;
+    correlationId: string;
+    userId?: string;
+    extraData?: E;
+}
+export interface QueueMessageInput<P = unknown, E = unknown> {
+    metadata: {
+        source: string;
+        eventType: string;
+        userId?: string;
+        correlationId?: string;
+        extraData?: E;
+    };
+    payload: P;
+}
+export type QueueSchemaInput<P = unknown, E = unknown> = {
+    metadata?: {
+        source?: string;
+        eventType?: string;
+        userId?: string;
+        correlationId?: string;
+        extraData?: E;
+    };
+    payload?: P;
+};
+export type IMetadata<E = unknown> = QueueMetadata<E>;
+export type IMessageInput<P = unknown, E = unknown> = QueueMessageInput<P, E>;
+export interface QueueMessage<P = unknown, E = unknown> {
+    metadata: QueueMetadata<E>;
+    payload: P;
+}

package/dist/dto/response/assemble.d.ts

@@ -0,0 +1 @@
+export { assembleResponseBody, type AssembleInput } from '../../core/assemble.js';

package/dist/dto/response/dto.d.ts

@@ -0,0 +1,39 @@
+import type { CodeMap } from '../../types/codes.js';
+import type { Payload, ResponseBody, SchemaInput } from '../../types/response.js';
+import { BaseDTO } from '../shared/base-dto.js';
+export interface ResponseBuildOptions {
+    codes?: CodeMap;
+    withDefaultBody?: boolean;
+    /** Used to infer `code` when it was not set on the chain (Builder passes HTTP status). */
+    httpStatusCode?: number;
+}
+/**
+ * Response body DTO — JSON only (`status → message → payload? → code`).
+ * Transport (HTTP status, headers, cookies) lives on {@link Builder}.
+ */
+export declare class ResponseDTO<T = unknown> extends BaseDTO<ResponseBody<T>, SchemaInput<T>> {
+    private _status?;
+    private _message?;
+    private _code?;
+    private _payload;
+    static status(value: boolean): ResponseDTO;
+    static message(value: string): ResponseDTO;
+    static code(value: number): ResponseDTO;
+    static data(data: unknown): ResponseDTO;
+    static payload(partial: Payload<unknown>): ResponseDTO;
+    static schema(input?: SchemaInput, codes?: CodeMap): ResponseDTO;
+    status(value: boolean): this;
+    message(msg: string): this;
+    code(code: number): this;
+    data(data: T | undefined): this;
+    payload(partial: Payload<T>): this;
+    setMeta(meta: Record<string, unknown>): this;
+    paginate(total: number, page: number, limit: number): this;
+    schema(input?: SchemaInput<T>, codes?: CodeMap): this;
+    getCode(): number | undefined;
+    getMessage(): string | undefined;
+    setCodeFromHttpStatus(httpStatusCode: number, codes: CodeMap): this;
+    transformData<U>(fn: (data: T) => U): ResponseDTO<U>;
+    build(options?: ResponseBuildOptions): ResponseBody<T>;
+    private buildPayload;
+}

package/dist/dto/response/index.cjs

@@ -0,0 +1,179 @@
+'use strict';
+
+// src/core/assemble.ts
+function assembleResponseBody(input) {
+  const ordered = {
+    status: input.status,
+    message: input.message
+  };
+  if (input.payload !== void 0 && Object.keys(input.payload).length > 0) {
+    ordered.payload = input.payload;
+  }
+  ordered.code = input.code;
+  return ordered;
+}
+
+// src/errors/codes.ts
+var DefaultCodes = {
+  SUCCESS: 0,
+  CLIENT: 1,
+  SERVER: 2,
+  VALIDATION: 3
+};
+function isSuccessCode(code, codes) {
+  return code === codes.SUCCESS;
+}
+function resolveCodeFromHttpStatus(statusCode, codes) {
+  if (statusCode >= 200 && statusCode < 300) return codes.SUCCESS;
+  if (statusCode === 422) return codes.VALIDATION;
+  if (statusCode >= 400 && statusCode < 500) return codes.CLIENT;
+  if (statusCode >= 500) return codes.SERVER;
+  if (statusCode >= 300 && statusCode < 400) return codes.SUCCESS;
+  return codes.CLIENT;
+}
+function defaultMessageForCode(code, codes) {
+  if (code === codes.SUCCESS) return "Operation successful";
+  if (code === codes.CLIENT) return "Client error";
+  if (code === codes.SERVER) return "Internal server error";
+  if (code === codes.VALIDATION) return "Validation failed";
+  return "Operation failed";
+}
+function resolveStatusFromCode(code, codes) {
+  return isSuccessCode(code, codes);
+}
+
+// src/dto/shared/base-dto.ts
+var BaseDTO = class {
+};
+
+// src/dto/response/dto.ts
+var ResponseDTO = class _ResponseDTO extends BaseDTO {
+  _status;
+  _message;
+  _code;
+  _payload = {};
+  static status(value) {
+    return new _ResponseDTO().status(value);
+  }
+  static message(value) {
+    return new _ResponseDTO().message(value);
+  }
+  static code(value) {
+    return new _ResponseDTO().code(value);
+  }
+  static data(data) {
+    return new _ResponseDTO().data(data);
+  }
+  static payload(partial) {
+    return new _ResponseDTO().payload(partial);
+  }
+  static schema(input = {}, codes = DefaultCodes) {
+    return new _ResponseDTO().schema(input, codes);
+  }
+  status(value) {
+    this._status = value;
+    return this;
+  }
+  message(msg) {
+    this._message = msg;
+    return this;
+  }
+  code(code) {
+    this._code = code;
+    return this;
+  }
+  data(data) {
+    if (data === void 0) {
+      delete this._payload.data;
+    } else {
+      this._payload.data = data;
+    }
+    return this;
+  }
+  payload(partial) {
+    this._payload = { ...this._payload, ...partial };
+    return this;
+  }
+  setMeta(meta) {
+    this._payload.meta = { ...this._payload.meta ?? {}, ...meta };
+    return this;
+  }
+  paginate(total, page, limit) {
+    if (limit <= 0) {
+      throw new Error("ResponseDTO.paginate: limit must be greater than 0");
+    }
+    this._payload.pagination = {
+      total,
+      page,
+      limit,
+      totalPages: Math.ceil(total / limit),
+      hasNext: page * limit < total
+    };
+    return this;
+  }
+  schema(input = {}, codes = DefaultCodes) {
+    const { status, message, code, payload } = input;
+    if (code !== void 0) {
+      this.code(code);
+    }
+    if (status !== void 0) {
+      this.status(status);
+    } else if (code !== void 0) {
+      this.status(resolveStatusFromCode(code, codes));
+    }
+    if (message !== void 0) {
+      this.message(message);
+    }
+    if (payload !== void 0) {
+      this._payload = { ...payload };
+    }
+    return this;
+  }
+  getCode() {
+    return this._code;
+  }
+  getMessage() {
+    return this._message;
+  }
+  setCodeFromHttpStatus(httpStatusCode, codes) {
+    if (this._code === void 0) {
+      this._code = resolveCodeFromHttpStatus(httpStatusCode, codes);
+    }
+    return this;
+  }
+  transformData(fn) {
+    const next = new _ResponseDTO();
+    next._status = this._status;
+    next._message = this._message;
+    next._code = this._code;
+    next._payload = { ...this._payload };
+    if (this._payload.data !== void 0) {
+      next._payload.data = fn(this._payload.data);
+    }
+    return next;
+  }
+  build(options = {}) {
+    const codes = options.codes ?? DefaultCodes;
+    const code = this._code ?? (options.httpStatusCode !== void 0 ? resolveCodeFromHttpStatus(options.httpStatusCode, codes) : codes.SUCCESS);
+    const status = this._status ?? isSuccessCode(code, codes);
+    const message = this._message ?? defaultMessageForCode(code, codes);
+    if (options.withDefaultBody === false) {
+      return assembleResponseBody({ status, message, code });
+    }
+    const payload = this.buildPayload();
+    return assembleResponseBody({
+      status,
+      message,
+      payload,
+      code
+    });
+  }
+  buildPayload() {
+    const entries = Object.entries(this._payload).filter(([, value]) => value !== void 0);
+    if (entries.length === 0) return void 0;
+    return Object.fromEntries(entries);
+  }
+};
+
+exports.ResponseDTO = ResponseDTO;
+exports.assembleResponseBody = assembleResponseBody;

package/dist/dto/response/index.d.ts

@@ -0,0 +1,2 @@
+export { assembleResponseBody, type AssembleInput } from './assemble.js';
+export { ResponseDTO, type ResponseBuildOptions } from './dto.js';

package/dist/dto/response/index.js

@@ -0,0 +1,176 @@
+// src/core/assemble.ts
+function assembleResponseBody(input) {
+  const ordered = {
+    status: input.status,
+    message: input.message
+  };
+  if (input.payload !== void 0 && Object.keys(input.payload).length > 0) {
+    ordered.payload = input.payload;
+  }
+  ordered.code = input.code;
+  return ordered;
+}
+
+// src/errors/codes.ts
+var DefaultCodes = {
+  SUCCESS: 0,
+  CLIENT: 1,
+  SERVER: 2,
+  VALIDATION: 3
+};
+function isSuccessCode(code, codes) {
+  return code === codes.SUCCESS;
+}
+function resolveCodeFromHttpStatus(statusCode, codes) {
+  if (statusCode >= 200 && statusCode < 300) return codes.SUCCESS;
+  if (statusCode === 422) return codes.VALIDATION;
+  if (statusCode >= 400 && statusCode < 500) return codes.CLIENT;
+  if (statusCode >= 500) return codes.SERVER;
+  if (statusCode >= 300 && statusCode < 400) return codes.SUCCESS;
+  return codes.CLIENT;
+}
+function defaultMessageForCode(code, codes) {
+  if (code === codes.SUCCESS) return "Operation successful";
+  if (code === codes.CLIENT) return "Client error";
+  if (code === codes.SERVER) return "Internal server error";
+  if (code === codes.VALIDATION) return "Validation failed";
+  return "Operation failed";
+}
+function resolveStatusFromCode(code, codes) {
+  return isSuccessCode(code, codes);
+}
+
+// src/dto/shared/base-dto.ts
+var BaseDTO = class {
+};
+
+// src/dto/response/dto.ts
+var ResponseDTO = class _ResponseDTO extends BaseDTO {
+  _status;
+  _message;
+  _code;
+  _payload = {};
+  static status(value) {
+    return new _ResponseDTO().status(value);
+  }
+  static message(value) {
+    return new _ResponseDTO().message(value);
+  }
+  static code(value) {
+    return new _ResponseDTO().code(value);
+  }
+  static data(data) {
+    return new _ResponseDTO().data(data);
+  }
+  static payload(partial) {
+    return new _ResponseDTO().payload(partial);
+  }
+  static schema(input = {}, codes = DefaultCodes) {
+    return new _ResponseDTO().schema(input, codes);
+  }
+  status(value) {
+    this._status = value;
+    return this;
+  }
+  message(msg) {
+    this._message = msg;
+    return this;
+  }
+  code(code) {
+    this._code = code;
+    return this;
+  }
+  data(data) {
+    if (data === void 0) {
+      delete this._payload.data;
+    } else {
+      this._payload.data = data;
+    }
+    return this;
+  }
+  payload(partial) {
+    this._payload = { ...this._payload, ...partial };
+    return this;
+  }
+  setMeta(meta) {
+    this._payload.meta = { ...this._payload.meta ?? {}, ...meta };
+    return this;
+  }
+  paginate(total, page, limit) {
+    if (limit <= 0) {
+      throw new Error("ResponseDTO.paginate: limit must be greater than 0");
+    }
+    this._payload.pagination = {
+      total,
+      page,
+      limit,
+      totalPages: Math.ceil(total / limit),
+      hasNext: page * limit < total
+    };
+    return this;
+  }
+  schema(input = {}, codes = DefaultCodes) {
+    const { status, message, code, payload } = input;
+    if (code !== void 0) {
+      this.code(code);
+    }
+    if (status !== void 0) {
+      this.status(status);
+    } else if (code !== void 0) {
+      this.status(resolveStatusFromCode(code, codes));
+    }
+    if (message !== void 0) {
+      this.message(message);
+    }
+    if (payload !== void 0) {
+      this._payload = { ...payload };
+    }
+    return this;
+  }
+  getCode() {
+    return this._code;
+  }
+  getMessage() {
+    return this._message;
+  }
+  setCodeFromHttpStatus(httpStatusCode, codes) {
+    if (this._code === void 0) {
+      this._code = resolveCodeFromHttpStatus(httpStatusCode, codes);
+    }
+    return this;
+  }
+  transformData(fn) {
+    const next = new _ResponseDTO();
+    next._status = this._status;
+    next._message = this._message;
+    next._code = this._code;
+    next._payload = { ...this._payload };
+    if (this._payload.data !== void 0) {
+      next._payload.data = fn(this._payload.data);
+    }
+    return next;
+  }
+  build(options = {}) {
+    const codes = options.codes ?? DefaultCodes;
+    const code = this._code ?? (options.httpStatusCode !== void 0 ? resolveCodeFromHttpStatus(options.httpStatusCode, codes) : codes.SUCCESS);
+    const status = this._status ?? isSuccessCode(code, codes);
+    const message = this._message ?? defaultMessageForCode(code, codes);
+    if (options.withDefaultBody === false) {
+      return assembleResponseBody({ status, message, code });
+    }
+    const payload = this.buildPayload();
+    return assembleResponseBody({
+      status,
+      message,
+      payload,
+      code
+    });
+  }
+  buildPayload() {
+    const entries = Object.entries(this._payload).filter(([, value]) => value !== void 0);
+    if (entries.length === 0) return void 0;
+    return Object.fromEntries(entries);
+  }
+};
+
+export { ResponseDTO, assembleResponseBody };