@zintrust/core 2.4.1 → 2.4.3

package/src/testing/TestHttp.d.ts

@@ -0,0 +1,29 @@
+import { type IRequest, type ValidatedRequest } from '../http/Request';
+import type { IResponse } from '../http/Response';
+export type TestHttpRequestInput = {
+    method?: string;
+    path?: string;
+    headers?: Record<string, string>;
+    body?: unknown;
+    params?: Record<string, string>;
+    validated?: IRequest['validated'];
+    context?: Record<string, unknown>;
+};
+export type TestHttpResponseRecorder = IResponse & {
+    getBodyText: () => string;
+    getJson: () => unknown;
+    getHeaders: () => Record<string, string | string[]>;
+};
+export declare const TestHttp: Readonly<{
+    createRequest(input?: TestHttpRequestInput): IRequest;
+    createValidatedRequest<TBody = unknown, TQuery = unknown, TParams = unknown, THeaders = unknown>(input: Omit<TestHttpRequestInput, "validated"> & {
+        validated: {
+            body: TBody;
+            query: TQuery;
+            params: TParams;
+            headers: THeaders;
+        };
+    }): ValidatedRequest<TBody, TQuery, TParams, THeaders>;
+    createResponseRecorder(): TestHttpResponseRecorder;
+}>;
+//# sourceMappingURL=TestHttp.d.ts.map

package/src/testing/TestHttp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"TestHttp.d.ts","sourceRoot":"","sources":["../../../src/testing/TestHttp.ts"],"names":[],"mappings":"AAAA,OAAO,EAAW,KAAK,QAAQ,EAAE,KAAK,gBAAgB,EAAE,MAAM,gBAAgB,CAAC;AAC/E,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGjD,MAAM,MAAM,oBAAoB,GAAG;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAChC,SAAS,CAAC,EAAE,QAAQ,CAAC,WAAW,CAAC,CAAC;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACnC,CAAC;AAEF,MAAM,MAAM,wBAAwB,GAAG,SAAS,GAAG;IACjD,WAAW,EAAE,MAAM,MAAM,CAAC;IAC1B,OAAO,EAAE,MAAM,OAAO,CAAC;IACvB,UAAU,EAAE,MAAM,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,EAAE,CAAC,CAAC;CACrD,CAAC;AAWF,eAAO,MAAM,QAAQ;0BACE,oBAAoB,GAAQ,QAAQ;2BAoBlC,KAAK,YAAY,MAAM,YAAY,OAAO,YAAY,QAAQ,mBAC5E,IAAI,CAAC,oBAAoB,EAAE,WAAW,CAAC,GAAG;QAC/C,SAAS,EAAE;YACT,IAAI,EAAE,KAAK,CAAC;YACZ,KAAK,EAAE,MAAM,CAAC;YACd,MAAM,EAAE,OAAO,CAAC;YAChB,OAAO,EAAE,QAAQ,CAAC;SACnB,CAAC;KACH,GACA,gBAAgB,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,QAAQ,CAAC;8BAS3B,wBAAwB;EAiElD,CAAC"}

package/src/testing/TestHttp.js

@@ -0,0 +1,96 @@
+import { Request } from '../http/Request.js';
+const lowerCaseHeaders = (headers) => {
+    if (!headers)
+        return {};
+    const out = {};
+    for (const [k, v] of Object.entries(headers))
+        out[k.toLowerCase()] = v;
+    return out;
+};
+const isError = (v) => v instanceof Error;
+export const TestHttp = Object.freeze({
+    createRequest(input = {}) {
+        const nodeReq = {
+            method: input.method ?? 'GET',
+            url: input.path ?? '/',
+            headers: lowerCaseHeaders(input.headers),
+        };
+        const req = Request.create(nodeReq);
+        if (input.body !== undefined)
+            req.setBody(input.body);
+        if (input.params !== undefined)
+            req.setParams(input.params);
+        const validated = input.validated;
+        if (validated !== undefined && validated !== null && !isError(validated)) {
+            req.validated = validated;
+        }
+        if (input.context !== undefined)
+            req.context = input.context;
+        return req;
+    },
+    createValidatedRequest(input) {
+        const req = this.createRequest({
+            ...input,
+            validated: input.validated,
+        });
+        return req;
+    },
+    createResponseRecorder() {
+        let statusCodeValue = 200;
+        let bodyText = '';
+        let jsonBody;
+        const headers = {};
+        const raw = {
+            statusCode: statusCodeValue,
+            writableEnded: false,
+            setHeader: (name, value) => {
+                headers[name] = value;
+            },
+            end: (data) => {
+                raw.writableEnded = true;
+                if (data === undefined)
+                    return;
+                bodyText += Buffer.isBuffer(data) ? data.toString('utf8') : String(data);
+            },
+        };
+        const res = {
+            locals: {},
+            status: (code) => res.setStatus(code),
+            setStatus: (code) => {
+                statusCodeValue = code;
+                raw.statusCode = code;
+                return res;
+            },
+            getStatus: () => statusCodeValue,
+            get statusCode() {
+                return statusCodeValue;
+            },
+            setHeader: (name, value) => {
+                headers[name] = value;
+                return res;
+            },
+            getHeader: (name) => headers[name],
+            json: (data) => {
+                jsonBody = data;
+                bodyText = JSON.stringify(data);
+            },
+            text: (text) => {
+                bodyText = text;
+            },
+            html: (html) => {
+                bodyText = html;
+            },
+            send: (data) => {
+                bodyText = Buffer.isBuffer(data) ? data.toString('utf8') : String(data);
+            },
+            redirect: (_url, code = 302) => {
+                statusCodeValue = code;
+            },
+            getRaw: () => raw,
+            getBodyText: () => bodyText,
+            getJson: () => jsonBody,
+            getHeaders: () => ({ ...headers }),
+        };
+        return res;
+    },
+});

package/src/testing/index.d.ts

@@ -0,0 +1,5 @@
+export { TestEnvironment } from '../testing/TestEnvironment';
+export type { ITestEnvironment, TestEnvironmentOptions, TestHeaders, TestRequestInput, TestResponse, } from '../testing/TestEnvironment';
+export { TestHttp } from '../testing/TestHttp';
+export type { TestHttpRequestInput, TestHttpResponseRecorder } from '../testing/TestHttp';
+//# sourceMappingURL=index.d.ts.map

package/src/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/testing/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,YAAY,EACV,gBAAgB,EAChB,sBAAsB,EACtB,WAAW,EACX,gBAAgB,EAChB,YAAY,GACb,MAAM,2BAA2B,CAAC;AAEnC,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC;AAC9C,YAAY,EAAE,oBAAoB,EAAE,wBAAwB,EAAE,MAAM,oBAAoB,CAAC"}

package/src/testing/index.js

@@ -0,0 +1,2 @@
+export { TestEnvironment } from '../testing/TestEnvironment.js';
+export { TestHttp } from '../testing/TestHttp.js';

package/src/testing-index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * ZinTrust Testing - Non-runtime entrypoint
+ * Contains test utilities and helpers for development use
+ */
+export { TestEnvironment } from './testing/TestEnvironment';
+export { TestHttp } from './testing/TestHttp';
+//# sourceMappingURL=testing-index.d.ts.map

package/src/testing-index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"testing-index.d.ts","sourceRoot":"","sources":["../../src/testing-index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAGH,OAAO,EAAE,eAAe,EAAE,MAAM,2BAA2B,CAAC;AAC5D,OAAO,EAAE,QAAQ,EAAE,MAAM,oBAAoB,CAAC"}

package/src/testing-index.js

@@ -0,0 +1,7 @@
+/**
+ * ZinTrust Testing - Non-runtime entrypoint
+ * Contains test utilities and helpers for development use
+ */
+// Testing utilities
+export { TestEnvironment } from './testing/TestEnvironment.js';
+export { TestHttp } from './testing/TestHttp.js';

package/src/time/DateTime.d.ts

@@ -0,0 +1,181 @@
+/**
+ * DateTime - Immutable Date/Time Utilities
+ * Provides chainable, type-safe date/time operations with multiple format support
+ */
+/**
+ * DateTime interface defining all available operations
+ */
+export interface IDateTime {
+    /**
+     * Get the underlying Date object
+     */
+    toDate(): Date;
+    /**
+     * Format the date using pattern tokens
+     * Supported tokens: YYYY, YY, MMMM, MMM, MM, M, DD, D, HH, H, mm, ss, SSS
+     */
+    format(pattern: string): string;
+    /**
+     * Convert to ISO 8601 string (YYYY-MM-DDTHH:mm:ss.sssZ)
+     */
+    toISO(): string;
+    /**
+     * Convert to RFC 3339 string (same as ISO 8601)
+     */
+    toRFC3339(): string;
+    /**
+     * Get human-readable relative time (e.g., "2 hours ago", "in 3 days")
+     */
+    ago(): string;
+    /**
+     * Get relative time from a specific date
+     */
+    relative(other: Date | IDateTime): string;
+    /**
+     * Add days to the date (returns new IDateTime)
+     */
+    addDays(days: number): IDateTime;
+    /**
+     * Add hours to the date (returns new IDateTime)
+     */
+    addHours(hours: number): IDateTime;
+    /**
+     * Add minutes to the date (returns new IDateTime)
+     */
+    addMinutes(minutes: number): IDateTime;
+    /**
+     * Add seconds to the date (returns new IDateTime)
+     */
+    addSeconds(seconds: number): IDateTime;
+    /**
+     * Add months to the date (returns new IDateTime)
+     */
+    addMonths(months: number): IDateTime;
+    /**
+     * Add years to the date (returns new IDateTime)
+     */
+    addYears(years: number): IDateTime;
+    /**
+     * Check if this date is before another date
+     */
+    isBefore(other: Date | IDateTime): boolean;
+    /**
+     * Check if this date is after another date
+     */
+    isAfter(other: Date | IDateTime): boolean;
+    /**
+     * Check if this date is the same as another date (ignoring time)
+     */
+    isSame(other: Date | IDateTime): boolean;
+    /**
+     * Check if this date is between two dates (inclusive)
+     */
+    isBetween(start: Date | IDateTime, end: Date | IDateTime): boolean;
+    /**
+     * Get difference in milliseconds from another date
+     */
+    diffMs(other: Date | IDateTime): number;
+    /**
+     * Get difference in seconds from another date
+     */
+    diffSeconds(other: Date | IDateTime): number;
+    /**
+     * Get difference in minutes from another date
+     */
+    diffMinutes(other: Date | IDateTime): number;
+    /**
+     * Get difference in hours from another date
+     */
+    diffHours(other: Date | IDateTime): number;
+    /**
+     * Get difference in days from another date
+     */
+    diffDays(other: Date | IDateTime): number;
+    /**
+     * Start of day (00:00:00)
+     */
+    startOfDay(): IDateTime;
+    /**
+     * End of day (23:59:59)
+     */
+    endOfDay(): IDateTime;
+    /**
+     * Start of month
+     */
+    startOfMonth(): IDateTime;
+    /**
+     * End of month
+     */
+    endOfMonth(): IDateTime;
+    /**
+     * Clone this datetime
+     */
+    clone(): IDateTime;
+    /**
+     * Get Unix timestamp (milliseconds since epoch)
+     */
+    getTime(): number;
+    /**
+     * Get year
+     */
+    getYear(): number;
+    /**
+     * Get month (0-11)
+     */
+    getMonth(): number;
+    /**
+     * Get day of month (1-31)
+     */
+    getDate(): number;
+    /**
+     * Get hours (0-23)
+     */
+    getHours(): number;
+    /**
+     * Get minutes (0-59)
+     */
+    getMinutes(): number;
+    /**
+     * Get seconds (0-59)
+     */
+    getSeconds(): number;
+    /**
+     * Get milliseconds (0-999)
+     */
+    getMilliseconds(): number;
+    /**
+     * Get day of week (0=Sunday, 6=Saturday)
+     */
+    getDayOfWeek(): number;
+    /**
+     * Get day of year (1-366)
+     */
+    getDayOfYear(): number;
+}
+/**
+ * DateTime namespace - sealed namespace object grouping all DateTime operations
+ * Immutable by design - all operations return new IDateTime instances
+ */
+export declare const DateTime: Readonly<{
+    /**
+     * Create a DateTime from a Date object
+     */
+    create(date?: Date): IDateTime;
+    /**
+     * Get current DateTime
+     */
+    now(): IDateTime;
+    /**
+     * Parse a date string
+     */
+    parse(dateString: string): IDateTime;
+    /**
+     * Create DateTime from timestamp (milliseconds since epoch)
+     */
+    fromTimestamp(timestamp: number): IDateTime;
+    /**
+     * Create DateTime from components
+     */
+    fromComponents(year: number, month: number, day?: number, hours?: number, minutes?: number, seconds?: number): IDateTime;
+}>;
+//# sourceMappingURL=DateTime.d.ts.map

package/src/time/DateTime.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"DateTime.d.ts","sourceRoot":"","sources":["../../../src/time/DateTime.ts"],"names":[],"mappings":"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"}

package/src/time/DateTime.js

@@ -0,0 +1,300 @@
+/**
+ * DateTime - Immutable Date/Time Utilities
+ * Provides chainable, type-safe date/time operations with multiple format support
+ */
+import { ErrorFactory } from '../exceptions/ZintrustError.js';
+/**
+ * Create a DateTime instance from a Date or string
+ */
+const monthNames = [
+    'January',
+    'February',
+    'March',
+    'April',
+    'May',
+    'June',
+    'July',
+    'August',
+    'September',
+    'October',
+    'November',
+    'December',
+];
+const monthNamesShort = [
+    'Jan',
+    'Feb',
+    'Mar',
+    'Apr',
+    'May',
+    'Jun',
+    'Jul',
+    'Aug',
+    'Sep',
+    'Oct',
+    'Nov',
+    'Dec',
+];
+const padZero = (num, length = 2) => {
+    return String(num).padStart(length, '0');
+};
+const getDayOfYearHelper = (date) => {
+    const start = new Date(date.getFullYear(), 0, 0);
+    const diff = date.getTime() - start.getTime();
+    const oneDay = 1000 * 60 * 60 * 24;
+    return Math.floor(diff / oneDay);
+};
+const calculateAgo = (value) => {
+    const now = new Date();
+    const diffMs = now.getTime() - value.getTime();
+    if (diffMs < 1000)
+        return 'just now';
+    if (diffMs < 60000)
+        return `${Math.floor(diffMs / 1000)} seconds ago`;
+    if (diffMs < 3600000)
+        return `${Math.floor(diffMs / 60000)} minutes ago`;
+    if (diffMs < 86400000)
+        return `${Math.floor(diffMs / 3600000)} hours ago`;
+    if (diffMs < 604800000)
+        return `${Math.floor(diffMs / 86400000)} days ago`;
+    if (diffMs < 2592000000)
+        return `${Math.floor(diffMs / 604800000)} weeks ago`;
+    if (diffMs < 31536000000)
+        return `${Math.floor(diffMs / 2592000000)} months ago`;
+    return `${Math.floor(diffMs / 31536000000)} years ago`;
+};
+const formatRelativeTime = (diffMs, isFuture) => {
+    const unit = (count, label) => isFuture ? `in ${count} ${label}` : `${count} ${label} ago`;
+    if (diffMs < 1000)
+        return 'just now';
+    if (diffMs < 60000)
+        return unit(Math.floor(diffMs / 1000), 'seconds');
+    if (diffMs < 3600000)
+        return unit(Math.floor(diffMs / 60000), 'minutes');
+    if (diffMs < 86400000)
+        return unit(Math.floor(diffMs / 3600000), 'hours');
+    if (diffMs < 604800000)
+        return unit(Math.floor(diffMs / 86400000), 'days');
+    if (diffMs < 2592000000)
+        return unit(Math.floor(diffMs / 604800000), 'weeks');
+    if (diffMs < 31536000000)
+        return unit(Math.floor(diffMs / 2592000000), 'months');
+    return unit(Math.floor(diffMs / 31536000000), 'years');
+};
+const calculateRelative = (value, other) => {
+    const otherDate = other instanceof Date ? other : other.toDate();
+    const diffMs = otherDate.getTime() - value.getTime();
+    if (diffMs < 0) {
+        return formatRelativeTime(Math.abs(diffMs), false);
+    }
+    return formatRelativeTime(diffMs, true);
+};
+const createAddMethods = (value) => {
+    return {
+        addDays: (days) => {
+            const newDate = new Date(value);
+            newDate.setDate(newDate.getDate() + days);
+            return createDateTime(newDate);
+        },
+        addHours: (hours) => {
+            const newDate = new Date(value);
+            newDate.setHours(newDate.getHours() + hours);
+            return createDateTime(newDate);
+        },
+        addMinutes: (minutes) => {
+            const newDate = new Date(value);
+            newDate.setMinutes(newDate.getMinutes() + minutes);
+            return createDateTime(newDate);
+        },
+        addSeconds: (seconds) => {
+            const newDate = new Date(value);
+            newDate.setSeconds(newDate.getSeconds() + seconds);
+            return createDateTime(newDate);
+        },
+        addMonths: (months) => {
+            const newDate = new Date(value);
+            newDate.setMonth(newDate.getMonth() + months);
+            return createDateTime(newDate);
+        },
+        addYears: (years) => {
+            const newDate = new Date(value);
+            newDate.setFullYear(newDate.getFullYear() + years);
+            return createDateTime(newDate);
+        },
+    };
+};
+const createCompareMethods = (value) => {
+    return {
+        isBefore: (other) => {
+            const otherDate = other instanceof Date ? other : other.toDate();
+            return value.getTime() < otherDate.getTime();
+        },
+        isAfter: (other) => {
+            const otherDate = other instanceof Date ? other : other.toDate();
+            return value.getTime() > otherDate.getTime();
+        },
+        isSame: (other) => {
+            const otherDate = other instanceof Date ? other : other.toDate();
+            return (value.getFullYear() === otherDate.getFullYear() &&
+                value.getMonth() === otherDate.getMonth() &&
+                value.getDate() === otherDate.getDate());
+        },
+        isBetween: (start, end) => {
+            const startDate = start instanceof Date ? start : start.toDate();
+            const endDate = end instanceof Date ? end : end.toDate();
+            return value.getTime() >= startDate.getTime() && value.getTime() <= endDate.getTime();
+        },
+    };
+};
+const createDiffMethods = (value) => {
+    const getOtherDate = (other) => other instanceof Date ? other : other.toDate();
+    return {
+        diffMs: (other) => {
+            return value.getTime() - getOtherDate(other).getTime();
+        },
+        diffSeconds: (other) => {
+            return Math.floor((value.getTime() - getOtherDate(other).getTime()) / 1000);
+        },
+        diffMinutes: (other) => {
+            return Math.floor((value.getTime() - getOtherDate(other).getTime()) / 60000);
+        },
+        diffHours: (other) => {
+            return Math.floor((value.getTime() - getOtherDate(other).getTime()) / 3600000);
+        },
+        diffDays: (other) => {
+            return Math.floor((value.getTime() - getOtherDate(other).getTime()) / 86400000);
+        },
+    };
+};
+const createBoundaryMethods = (value) => {
+    return {
+        startOfDay: () => {
+            const newDate = new Date(value);
+            newDate.setHours(0, 0, 0, 0);
+            return createDateTime(newDate);
+        },
+        endOfDay: () => {
+            const newDate = new Date(value);
+            newDate.setHours(23, 59, 59, 999);
+            return createDateTime(newDate);
+        },
+        startOfMonth: () => {
+            const newDate = new Date(value);
+            newDate.setDate(1);
+            newDate.setHours(0, 0, 0, 0);
+            return createDateTime(newDate);
+        },
+        endOfMonth: () => {
+            const newDate = new Date(value);
+            newDate.setMonth(newDate.getMonth() + 1);
+            newDate.setDate(0);
+            newDate.setHours(23, 59, 59, 999);
+            return createDateTime(newDate);
+        },
+    };
+};
+const createDateTime = (date) => {
+    // Create a copy to ensure immutability
+    const value = new Date(date);
+    const addMethods = createAddMethods(value);
+    const compareMethods = createCompareMethods(value);
+    const diffMethods = createDiffMethods(value);
+    const boundaryMethods = createBoundaryMethods(value);
+    return {
+        toDate: () => new Date(value),
+        format: (pattern) => {
+            let result = pattern;
+            const year = value.getFullYear();
+            const month = value.getMonth();
+            const day = value.getDate();
+            const hours = value.getHours();
+            const minutes = value.getMinutes();
+            const seconds = value.getSeconds();
+            const milliseconds = value.getMilliseconds();
+            // Replace tokens in the pattern
+            result = result.replaceAll('YYYY', String(year));
+            result = result.replaceAll('YY', String(year).slice(-2));
+            result = result.replaceAll('MMMM', monthNames[month] ?? '');
+            result = result.replaceAll('MMM', monthNamesShort[month] ?? '');
+            result = result.replaceAll('MM', padZero(month + 1));
+            result = result.replaceAll('M', String(month + 1));
+            result = result.replaceAll('DD', padZero(day));
+            result = result.replaceAll('D', String(day));
+            result = result.replaceAll('HH', padZero(hours));
+            result = result.replaceAll('H', String(hours));
+            result = result.replaceAll('mm', padZero(minutes));
+            result = result.replaceAll('m', String(minutes));
+            result = result.replaceAll('ss', padZero(seconds));
+            result = result.replaceAll('s', String(seconds));
+            result = result.replaceAll('SSS', padZero(milliseconds, 3));
+            result = result.replaceAll('S', String(milliseconds));
+            return result;
+        },
+        toISO: () => value.toISOString(),
+        toRFC3339: () => value.toISOString(),
+        ago: () => calculateAgo(value),
+        relative: (other) => calculateRelative(value, other),
+        ...addMethods,
+        ...compareMethods,
+        ...diffMethods,
+        ...boundaryMethods,
+        clone: () => createDateTime(new Date(value)),
+        getTime: () => value.getTime(),
+        getYear: () => value.getFullYear(),
+        getMonth: () => value.getMonth(),
+        getDate: () => value.getDate(),
+        getHours: () => value.getHours(),
+        getMinutes: () => value.getMinutes(),
+        getSeconds: () => value.getSeconds(),
+        getMilliseconds: () => value.getMilliseconds(),
+        getDayOfWeek: () => value.getDay(),
+        getDayOfYear: () => getDayOfYearHelper(value),
+    };
+};
+/**
+ * Parse a date string into a DateTime object
+ * Supports: ISO 8601, RFC 3339, common formats
+ */
+const parse = (dateString) => {
+    // Try to parse as ISO 8601 / RFC 3339
+    const parsedDate = new Date(dateString);
+    if (Number.isNaN(parsedDate.getTime())) {
+        throw ErrorFactory.createValidationError(`Invalid date string: ${dateString}`);
+    }
+    return createDateTime(parsedDate);
+};
+/**
+ * DateTime namespace - sealed namespace object grouping all DateTime operations
+ * Immutable by design - all operations return new IDateTime instances
+ */
+export const DateTime = Object.freeze({
+    /**
+     * Create a DateTime from a Date object
+     */
+    create(date = new Date()) {
+        return createDateTime(date);
+    },
+    /**
+     * Get current DateTime
+     */
+    now() {
+        return createDateTime(new Date());
+    },
+    /**
+     * Parse a date string
+     */
+    parse(dateString) {
+        return parse(dateString);
+    },
+    /**
+     * Create DateTime from timestamp (milliseconds since epoch)
+     */
+    fromTimestamp(timestamp) {
+        return createDateTime(new Date(timestamp));
+    },
+    /**
+     * Create DateTime from components
+     */
+    fromComponents(year, month, day = 1, hours = 0, minutes = 0, seconds = 0) {
+        return createDateTime(new Date(year, month - 1, day, hours, minutes, seconds));
+    },
+});

package/src/time/index.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Time Utilities Module
+ * Exports immutable DateTime utilities and related types
+ */
+export { DateTime } from './DateTime';
+export type { IDateTime } from './DateTime';
+//# sourceMappingURL=index.d.ts.map

package/src/time/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/time/index.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC1C,YAAY,EAAE,SAAS,EAAE,MAAM,gBAAgB,CAAC"}

package/src/time/index.js

@@ -0,0 +1,5 @@
+/**
+ * Time Utilities Module
+ * Exports immutable DateTime utilities and related types
+ */
+export { DateTime } from './DateTime.js';

package/src/toolkit/Secrets/EnvFile.d.ts

@@ -0,0 +1,15 @@
+export type EnvFileWriteMode = 'overwrite';
+export declare const EnvFile: Readonly<{
+    read(params: {
+        cwd: string;
+        path: string;
+    }): Promise<Record<string, string>>;
+    write(params: {
+        cwd: string;
+        path: string;
+        values: Record<string, string>;
+        mode: EnvFileWriteMode;
+    }): Promise<void>;
+}>;
+export default EnvFile;
+//# sourceMappingURL=EnvFile.d.ts.map