@zintrust/core 0.1.28 → 0.1.29

package/src/http/Request.js

@@ -0,0 +1,237 @@
+/**
+ * Request - HTTP Request wrapper
+ * Wraps Node.js IncomingMessage with additional utilities
+ */
+import { FileUpload } from './FileUpload.js';
+/**
+ * Request - HTTP Request wrapper
+ * Refactored to Functional Object pattern
+ */
+/**
+ * Parse query string from URL
+ */
+const parseQuery = (urlStr) => {
+    const query = {};
+    const url = new URL(urlStr, 'http://localhost');
+    url.searchParams.forEach((value, key) => {
+        const existing = query[key];
+        if (existing === undefined) {
+            query[key] = value;
+        }
+        else if (Array.isArray(existing)) {
+            existing.push(value);
+        }
+        else {
+            query[key] = [existing, value];
+        }
+    });
+    return query;
+};
+const isPlainObject = (value) => {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+};
+const toBodyRecord = (value) => {
+    return isPlainObject(value) ? value : {};
+};
+const createRequestState = (req) => {
+    return {
+        sessionId: req.headers['x-session-id'],
+        user: undefined,
+        params: {},
+        body: null,
+        bodyRecord: {},
+        validated: {},
+        _cachedData: undefined,
+    };
+};
+const setBodyState = (state, newBody) => {
+    state.body = newBody;
+    state.bodyRecord = toBodyRecord(newBody);
+    state._cachedData = undefined; // Clear cache when body changes
+};
+const createRequestProperties = (state, context) => {
+    return {
+        get sessionId() {
+            return state.sessionId;
+        },
+        set sessionId(newSessionId) {
+            state.sessionId = newSessionId;
+        },
+        get user() {
+            return state.user;
+        },
+        set user(newUser) {
+            state.user = newUser;
+        },
+        context,
+        get params() {
+            return state.params;
+        },
+        set params(newParams) {
+            state.params = newParams;
+        },
+        get body() {
+            return state.bodyRecord;
+        },
+        set body(newBody) {
+            setBodyState(state, newBody);
+        },
+        get validated() {
+            return state.validated;
+        },
+        set validated(v) {
+            state.validated = v;
+        },
+    };
+};
+/**
+ * Create HTTP method helpers
+ */
+function createHttpHelpers(req) {
+    return {
+        getMethod() {
+            return req.method ?? 'GET';
+        },
+        getPath() {
+            const url = req.url;
+            return url === undefined ? '/' : url.split('?')[0];
+        },
+        getHeaders() {
+            return req.headers;
+        },
+        get headers() {
+            return req.headers;
+        },
+        getHeader(name) {
+            return req.headers[name.toLowerCase()];
+        },
+    };
+}
+/**
+ * Create parameter helpers
+ */
+function createParameterHelpers(state, query) {
+    return {
+        getParams() {
+            return state.params;
+        },
+        getParam(key) {
+            return state.params[key];
+        },
+        setParams(newParams) {
+            state.params = newParams;
+            state._cachedData = undefined; // Clear cache when params change
+        },
+        getQuery() {
+            return query;
+        },
+        getQueryParam(key) {
+            return query[key];
+        },
+    };
+}
+/**
+ * Create body helpers
+ */
+function createBodyHelpers(state, req) {
+    return {
+        setBody(newBody) {
+            setBodyState(state, newBody);
+        },
+        getBody() {
+            return state.body;
+        },
+        isJson() {
+            const contentType = req.headers['content-type'];
+            return typeof contentType === 'string' && contentType.includes('application/json');
+        },
+    };
+}
+/**
+ * Create file upload helpers
+ */
+function createFileHelpers(getCompleteRequest) {
+    return {
+        file(fieldName, options) {
+            const handler = FileUpload.createHandler(getCompleteRequest());
+            return handler.file(fieldName, options);
+        },
+        files(fieldName, options) {
+            const handler = FileUpload.createHandler(getCompleteRequest());
+            return handler.files(fieldName, options);
+        },
+        hasFile(fieldName) {
+            const handler = FileUpload.createHandler(getCompleteRequest());
+            return handler.hasFile(fieldName);
+        },
+        fileUpload() {
+            return FileUpload.createHandler(getCompleteRequest());
+        },
+    };
+}
+/**
+ * Create unified data helpers
+ */
+function createDataHelpers(state, query) {
+    return {
+        data() {
+            // Precedence: Body > Path Params > Query Params
+            state._cachedData ??= {
+                ...query,
+                ...state.params,
+                ...state.bodyRecord,
+            };
+            return state._cachedData;
+        },
+        get(key, defaultValue) {
+            const data = this.data();
+            return data[key] ?? defaultValue;
+        },
+    };
+}
+const createRequestMethods = (req, query, state, context) => {
+    return {
+        ...createHttpHelpers(req),
+        ...createParameterHelpers(state, query),
+        ...createBodyHelpers(state, req),
+        ...createFileHelpers(() => {
+            // Create a complete request object for file handlers
+            const completeRequest = {
+                ...createHttpHelpers(req),
+                ...createParameterHelpers(state, query),
+                ...createBodyHelpers(state, req),
+                ...createDataHelpers(state, query),
+                getRaw: () => req,
+                sessionId: state.sessionId,
+                user: state.user,
+                params: state.params,
+                body: state.body,
+                validated: state.validated,
+                context,
+            };
+            return completeRequest;
+        }),
+        ...createDataHelpers(state, query),
+        getRaw() {
+            return req;
+        },
+    };
+};
+const createRequestApi = (req, query, context, state) => {
+    return {
+        ...createRequestProperties(state, context),
+        ...createRequestMethods(req, query, state, context),
+    };
+};
+export const Request = Object.freeze({
+    /**
+     * Create a new request instance
+     */
+    create(req) {
+        const query = parseQuery(req.url ?? '/');
+        const context = {};
+        const state = createRequestState(req);
+        return createRequestApi(req, query, context, state);
+    },
+});
+export default Request;

package/src/http/RequestContext.d.ts

@@ -0,0 +1,26 @@
+import type { IRequest } from './Request';
+export interface IRequestContext {
+    requestId: string;
+    traceId?: string;
+    userId?: string;
+    tenantId?: string;
+    startTime: number;
+    method: string;
+    path: string;
+    userAgent?: string;
+    status?: number;
+    duration?: number;
+}
+export declare const RequestContext: Readonly<{
+    run<T>(context: IRequestContext, callback: () => T): Promise<T>;
+    current(): Promise<IRequestContext | undefined>;
+    create(req: IRequest): IRequestContext;
+    attach(req: IRequest, context: IRequestContext): void;
+    get(req: IRequest): IRequestContext | undefined;
+    enrich(context: IRequestContext, status: number): IRequestContext;
+    setUserId(req: IRequest, userId: string | undefined): void;
+    setTenantId(req: IRequest, tenantId: string | undefined): void;
+    setTraceId(req: IRequest, traceId: string | undefined): void;
+}>;
+export default RequestContext;
+//# sourceMappingURL=RequestContext.d.ts.map

package/src/http/RequestContext.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"RequestContext.d.ts","sourceRoot":"","sources":["../../../src/http/RequestContext.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAE9C,MAAM,WAAW,eAAe;IAC9B,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,SAAS,EAAE,MAAM,CAAC;IAClB,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,EAAE,MAAM,CAAC;IACb,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,QAAQ,CAAC,EAAE,MAAM,CAAC;CACnB;AAgGD,eAAO,MAAM,cAAc;QACf,CAAC,WAAW,eAAe,YAAY,MAAM,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC;eAKpD,OAAO,CAAC,eAAe,GAAG,SAAS,CAAC;gBAKzC,QAAQ,GAAG,eAAe;gBAmC1B,QAAQ,WAAW,eAAe,GAAG,IAAI;aAS5C,QAAQ,GAAG,eAAe,GAAG,SAAS;oBAM/B,eAAe,UAAU,MAAM,GAAG,eAAe;mBASlD,QAAQ,UAAU,MAAM,GAAG,SAAS,GAAG,IAAI;qBAIzC,QAAQ,YAAY,MAAM,GAAG,SAAS,GAAG,IAAI;oBAI9C,QAAQ,WAAW,MAAM,GAAG,SAAS,GAAG,IAAI;EAG5D,CAAC;AAEH,eAAe,cAAc,CAAC"}

package/src/http/RequestContext.js

@@ -0,0 +1,153 @@
+import { generateUuid } from '../common/utility.js';
+const createFallbackStorage = () => {
+    let store;
+    return {
+        run(ctx, callback) {
+            const prev = store;
+            store = ctx;
+            try {
+                return callback();
+            }
+            finally {
+                store = prev;
+            }
+        },
+        getStore() {
+            return store;
+        },
+    };
+};
+const resolveStorage = async () => {
+    try {
+        const mod = (await import('../node-singletons/async_hooks.js'));
+        return new mod.AsyncLocalStorage();
+    }
+    catch {
+        return createFallbackStorage();
+    }
+};
+const getHeaderString = (req, name) => {
+    const value = req.getHeader(name);
+    return typeof value === 'string' ? value : undefined;
+};
+const extractTraceIdFromTraceparent = (traceparent) => {
+    if (typeof traceparent !== 'string')
+        return undefined;
+    const trimmed = traceparent.trim();
+    if (trimmed === '')
+        return undefined;
+    // W3C traceparent: version-traceid-spanid-flags
+    // Example: 00-4bf92f3577b34da6a3ce929d0e0e4736-00f067aa0ba902b7-01
+    const parts = trimmed.split('-');
+    if (parts.length !== 4)
+        return undefined;
+    const traceId = parts[1] ?? '';
+    if (/^[0-9a-f]{32}$/i.test(traceId) === false)
+        return undefined;
+    // Disallow all-zero traceId
+    if (/^0{32}$/i.test(traceId))
+        return undefined;
+    return traceId.toLowerCase();
+};
+const getTraceIdFromMicroserviceTraceContext = (req) => {
+    const anyReq = req;
+    const trace = anyReq.context?.['trace'];
+    if (typeof trace !== 'object' || trace === null)
+        return undefined;
+    const traceId = trace.traceId;
+    return typeof traceId === 'string' && traceId.trim() !== '' ? traceId : undefined;
+};
+const getOptionalContextString = (req, key) => {
+    const anyReq = req;
+    const value = anyReq.context?.[key];
+    if (typeof value === 'string')
+        return value;
+    if (typeof value === 'number')
+        return String(value);
+    return undefined;
+};
+const setContextField = (req, field, value) => {
+    req.context ??= {};
+    if (typeof value === 'string' && value.trim() !== '') {
+        req.context[field] = value;
+    }
+    const ctx = RequestContext.get(req);
+    if (ctx) {
+        ctx[field] = value;
+    }
+};
+const STORAGE_PROMISE = resolveStorage();
+export const RequestContext = Object.freeze({
+    async run(context, callback) {
+        const storage = await STORAGE_PROMISE;
+        return storage.run(context, callback);
+    },
+    async current() {
+        const storage = await STORAGE_PROMISE;
+        return storage.getStore();
+    },
+    create(req) {
+        req.context ??= {};
+        const requestIdFromHeader = getHeaderString(req, 'x-request-id');
+        const requestId = requestIdFromHeader ?? generateUuid();
+        const traceId = extractTraceIdFromTraceparent(getHeaderString(req, 'traceparent')) ??
+            getHeaderString(req, 'x-trace-id') ??
+            getTraceIdFromMicroserviceTraceContext(req) ??
+            getOptionalContextString(req, 'traceId');
+        const userId = getOptionalContextString(req, 'userId');
+        const tenantId = getOptionalContextString(req, 'tenantId');
+        const ctx = {
+            requestId,
+            traceId,
+            userId,
+            tenantId,
+            startTime: Date.now(),
+            method: req.getMethod(),
+            path: req.getPath(),
+            userAgent: getHeaderString(req, 'user-agent'),
+        };
+        req.context['requestId'] = requestId;
+        if (traceId !== undefined)
+            req.context['traceId'] = traceId;
+        if (userId !== undefined)
+            req.context['userId'] = userId;
+        if (tenantId !== undefined)
+            req.context['tenantId'] = tenantId;
+        req.context['requestContext'] = ctx;
+        return ctx;
+    },
+    attach(req, context) {
+        req.context ??= {};
+        req.context['requestContext'] = context;
+        req.context['requestId'] = context.requestId;
+        if (context.traceId !== undefined)
+            req.context['traceId'] = context.traceId;
+        if (context.userId !== undefined)
+            req.context['userId'] = context.userId;
+        if (context.tenantId !== undefined)
+            req.context['tenantId'] = context.tenantId;
+    },
+    get(req) {
+        const anyReq = req;
+        const value = anyReq.context?.['requestContext'];
+        return typeof value === 'object' && value !== null ? value : undefined;
+    },
+    enrich(context, status) {
+        const duration = Date.now() - context.startTime;
+        return {
+            ...context,
+            status,
+            duration,
+        };
+    },
+    setUserId(req, userId) {
+        setContextField(req, 'userId', userId);
+    },
+    setTenantId(req, tenantId) {
+        setContextField(req, 'tenantId', tenantId);
+    },
+    setTraceId(req, traceId) {
+        setContextField(req, 'traceId', traceId);
+    },
+});
+export default RequestContext;

package/src/http/Response.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Response - HTTP Response wrapper
+ * Wraps Node.js ServerResponse with additional utilities
+ */
+import type * as http from '../node-singletons/http';
+export interface IResponse {
+    status(code: number): IResponse;
+    setStatus(code: number): IResponse;
+    getStatus(): number;
+    readonly statusCode: number;
+    setHeader(name: string, value: string | string[]): IResponse;
+    getHeader(name: string): string | string[] | undefined;
+    json(data: unknown): void;
+    text(text: string): void;
+    html(html: string): void;
+    send(data: string | Buffer): void;
+    redirect(url: string, statusCode?: number): void;
+    getRaw(): http.ServerResponse;
+    locals: Record<string, unknown>;
+}
+/**
+ * Response - HTTP Response wrapper
+ * Refactored to Functional Object pattern
+ */
+export declare const Response: Readonly<{
+    /**
+     * Create a new response instance
+     */
+    create(res: http.ServerResponse): IResponse;
+}>;
+export default Response;
+//# sourceMappingURL=Response.d.ts.map

package/src/http/Response.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"Response.d.ts","sourceRoot":"","sources":["../../../src/http/Response.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,KAAK,IAAI,MAAM,uBAAuB,CAAC;AAEnD,MAAM,WAAW,SAAS;IACxB,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IAChC,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,CAAC;IACnC,SAAS,IAAI,MAAM,CAAC;IACpB,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IAC7D,SAAS,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC;IACvD,IAAI,CAAC,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;IAC1B,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACzB,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAAC;IAClC,QAAQ,CAAC,GAAG,EAAE,MAAM,EAAE,UAAU,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;IACjD,MAAM,IAAI,IAAI,CAAC,cAAc,CAAC;IAC9B,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACjC;AAED;;;GAGG;AACH,eAAO,MAAM,QAAQ;IACnB;;OAEG;gBACS,IAAI,CAAC,cAAc,GAAG,SAAS;EA0D3C,CAAC;AAEH,eAAe,QAAQ,CAAC"}

package/src/http/Response.js

@@ -0,0 +1,70 @@
+/**
+ * Response - HTTP Response wrapper
+ * Wraps Node.js ServerResponse with additional utilities
+ */
+import { HTTP_HEADERS, MIME_TYPES } from '../config/constants.js';
+/**
+ * Response - HTTP Response wrapper
+ * Refactored to Functional Object pattern
+ */
+export const Response = Object.freeze({
+    /**
+     * Create a new response instance
+     */
+    create(res) {
+        let statusCodeValue = 200;
+        const headers = {};
+        const locals = {};
+        const response = {
+            locals,
+            status(code) {
+                return this.setStatus(code);
+            },
+            setStatus(code) {
+                statusCodeValue = code;
+                res.statusCode = code;
+                return this;
+            },
+            getStatus() {
+                return statusCodeValue;
+            },
+            get statusCode() {
+                return statusCodeValue;
+            },
+            setHeader(name, value) {
+                headers[name] = value;
+                res.setHeader(name, value);
+                return this;
+            },
+            getHeader(name) {
+                return headers[name];
+            },
+            json(data) {
+                this.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.JSON);
+                res.end(JSON.stringify(data));
+            },
+            text(text) {
+                this.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.TEXT);
+                res.end(text);
+            },
+            html(html) {
+                this.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.HTML);
+                res.end(html);
+            },
+            send(data) {
+                res.end(data);
+            },
+            redirect(url, statusCode = 302) {
+                this.setStatus(statusCode);
+                this.setHeader('Location', url);
+                res.end();
+            },
+            getRaw() {
+                return res;
+            },
+        };
+        response.setHeader(HTTP_HEADERS.CONTENT_TYPE, MIME_TYPES.JSON);
+        return response;
+    },
+});
+export default Response;

package/src/http/ValidationHelper.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Validation Helper
+ * Utilities for working with validated request data
+ */
+import type { IRequest } from './Request';
+/**
+ * Extract validated body from request
+ * Returns the validated body if present, undefined otherwise
+ *
+ * @example
+ * ```typescript
+ * const body = getValidatedBody(req);
+ * if (!body) {
+ *   Logger.error('Validation middleware not configured');
+ *   return res.setStatus(500).json({ error: 'Internal server error' });
+ * }
+ * const email = getString(body['email']);
+ * ```
+ */
+export declare function getValidatedBody<T = Record<string, unknown>>(req: IRequest): T | undefined;
+/**
+ * Check if request has a validated body
+ * Type guard for validated body existence
+ *
+ * @example
+ * ```typescript
+ * if (!hasValidatedBody(req)) {
+ *   Logger.error('Validation middleware not configured');
+ *   return res.setStatus(500).json({ error: 'Internal server error' });
+ * }
+ * const body = getValidatedBody(req)!; // Safe to use non-null assertion
+ * ```
+ */
+export declare function hasValidatedBody(req: IRequest): boolean;
+/**
+ * Extract validated body or throw error
+ * Throws if validation middleware is not properly configured
+ *
+ * @example
+ * ```typescript
+ * try {
+ *   const body = requireValidatedBody(req);
+ *   const email = getString(body['email']);
+ * } catch (error) {
+ *   Logger.error('Validation middleware error', error);
+ *   return res.setStatus(500).json({ error: 'Internal server error' });
+ * }
+ * ```
+ */
+export declare function requireValidatedBody<T = Record<string, unknown>>(req: IRequest): T;
+/**
+ * Extract validated query parameters from request
+ * Returns the validated query if present, undefined otherwise
+ */
+export declare function getValidatedQuery<T = Record<string, unknown>>(req: IRequest): T | undefined;
+/**
+ * Extract validated route parameters from request
+ * Returns the validated params if present, undefined otherwise
+ */
+export declare function getValidatedParams<T = Record<string, unknown>>(req: IRequest): T | undefined;
+/**
+ * Extract validated headers from request
+ * Returns the validated headers if present, undefined otherwise
+ */
+export declare function getValidatedHeaders<T = Record<string, unknown>>(req: IRequest): T | undefined;
+/**
+ * Validation Helper - Sealed namespace
+ */
+export declare const ValidationHelper: Readonly<{
+    getValidatedBody: typeof getValidatedBody;
+    hasValidatedBody: typeof hasValidatedBody;
+    requireValidatedBody: typeof requireValidatedBody;
+    getValidatedQuery: typeof getValidatedQuery;
+    getValidatedParams: typeof getValidatedParams;
+    getValidatedHeaders: typeof getValidatedHeaders;
+}>;
+export default ValidationHelper;
+//# sourceMappingURL=ValidationHelper.d.ts.map

package/src/http/ValidationHelper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"ValidationHelper.d.ts","sourceRoot":"","sources":["../../../src/http/ValidationHelper.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAC;AAa9C;;;;;;;;;;;;;GAaG;AACH,wBAAgB,gBAAgB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,GAAG,SAAS,CAK1F;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,gBAAgB,CAAC,GAAG,EAAE,QAAQ,GAAG,OAAO,CAKvD;AAED;;;;;;;;;;;;;;GAcG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,CAQlF;AAED;;;GAGG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,GAAG,SAAS,CAK3F;AAED;;;GAGG;AACH,wBAAgB,kBAAkB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,GAAG,SAAS,CAK5F;AAED;;;GAGG;AACH,wBAAgB,mBAAmB,CAAC,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,GAAG,EAAE,QAAQ,GAAG,CAAC,GAAG,SAAS,CAK7F;AAED;;GAEG;AACH,eAAO,MAAM,gBAAgB;;;;;;;EAO3B,CAAC;AAEH,eAAe,gBAAgB,CAAC"}