@cookbook/urlkit 1.0.0 → 1.2.0

package/dist/{compile-path-wQfWAzOh.js → compile-path-oMMfpXR8.js}

@@ -1,6 +1,7 @@
 import compile from '@cookbook/pathkit/compile';
 import match from '@cookbook/pathkit/match';
-import { hasConstraint, getConstraint, registerConstraint, createConstraint } from '@cookbook/pathkit/constraints';
+import { hasConstraint, getConstraint, registerConstraint } from '@cookbook/pathkit/constraints';
+import tokenize from '@cookbook/pathkit/tokenize';
 
 const defaultMessages = {
     'invalid-url': 'Invalid URL.',
@@ -325,6 +326,209 @@ function validateBooleanDefault(value, context) {
     });
 }
 
+const supportedTokens = ['yyyy', 'SSS', 'MM', 'dd', 'HH', 'mm', 'ss'];
+const dateTokens = new Set(['yyyy', 'MM', 'dd']);
+const dateTimeTokens = new Set(['yyyy', 'MM', 'dd', 'HH', 'mm', 'ss', 'SSS']);
+function parseDateFormatString(input, format, mode, options = {}) {
+    const compiled = compileDateFormatString(format, mode);
+    const match = compiled.pattern.exec(input);
+    if (!match?.groups) {
+        throw createDateFormatStringError(`${getFormatLabel(mode)} value must match format "${format}".`, options);
+    }
+    const parts = readDateParts(match.groups, compiled);
+    assertValidDateParts(parts, mode, options);
+    const value = new Date(Date.UTC(0, parts.month - 1, parts.day, parts.hour, parts.minute, parts.second, parts.millisecond));
+    value.setUTCFullYear(parts.year);
+    if (!matchesDateParts(value, parts)) {
+        throw createDateFormatStringError(`${getFormatLabel(mode)} value must be a valid UTC calendar ${mode === 'date' ? 'date' : 'instant'}.`, options);
+    }
+    return value;
+}
+function serializeDateFormatString(input, format, mode, options = {}) {
+    if (!(input instanceof Date) || !Number.isFinite(input.getTime())) {
+        throw createDateFormatStringError(`${getFormatLabel(mode)} value must be a valid Date.`, options);
+    }
+    const compiled = compileDateFormatString(format, mode);
+    const year = input.getUTCFullYear();
+    if (year < 0 || year > 9999) {
+        throw createDateFormatStringError(`${getFormatLabel(mode)} value year must be between 0000 and 9999 for yyyy format strings.`, options);
+    }
+    if (mode === 'date-time' && !compiled.hasMilliseconds && input.getUTCMilliseconds() !== 0) {
+        throw createDateFormatStringError('Date-time value cannot be serialized without losing milliseconds. Include SSS in the format or use a Date with zero milliseconds.', options);
+    }
+    return compiled.parts
+        .map((part) => {
+        if (part.kind === 'literal') {
+            return part.value;
+        }
+        return serializeToken(input, part.value);
+    })
+        .join('');
+}
+function validateDateFormatString(format, mode) {
+    compileDateFormatString(format, mode);
+}
+function compileDateFormatString(format, mode) {
+    const parts = tokenizeDateFormatString(format, mode);
+    validateDateFormatParts(format, parts, mode);
+    const pattern = new RegExp(`^${parts
+        .map((part) => part.kind === 'literal' ? escapeRegExp(part.value) : getTokenPattern(part.value))
+        .join('')}$`);
+    return {
+        format,
+        mode,
+        parts,
+        pattern,
+        hasMilliseconds: parts.some((part) => part.kind === 'token' && part.value === 'SSS'),
+    };
+}
+function tokenizeDateFormatString(format, mode) {
+    if (typeof format !== 'string' || format.length === 0) {
+        throw createInvalidDateFormatDescriptorError(`${getFormatLabel(mode)} format must be a non-empty string.`);
+    }
+    const parts = [];
+    let index = 0;
+    while (index < format.length) {
+        if (format[index] === "'") {
+            const literalEnd = format.indexOf("'", index + 1);
+            if (literalEnd === -1) {
+                throw createInvalidDateFormatDescriptorError(`${getFormatLabel(mode)} format contains an unterminated quoted literal.`);
+            }
+            const literal = format.slice(index + 1, literalEnd);
+            if (literal.length === 0) {
+                throw createInvalidDateFormatDescriptorError(`${getFormatLabel(mode)} format contains an empty quoted literal.`);
+            }
+            parts.push({ kind: 'literal', value: literal });
+            index = literalEnd + 1;
+            continue;
+        }
+        const token = findTokenAt(format, index);
+        if (token) {
+            parts.push({ kind: 'token', value: token });
+            index += token.length;
+            continue;
+        }
+        const character = format[index] ?? '';
+        if (isAsciiLetter(character)) {
+            throw createInvalidDateFormatDescriptorError(`${getFormatLabel(mode)} format contains unsupported token near "${format.slice(index)}".`);
+        }
+        parts.push({ kind: 'literal', value: character });
+        index += 1;
+    }
+    return mergeAdjacentLiterals(parts);
+}
+function findTokenAt(format, index) {
+    return supportedTokens.find((token) => format.startsWith(token, index));
+}
+function mergeAdjacentLiterals(parts) {
+    const merged = [];
+    for (const part of parts) {
+        const previous = merged[merged.length - 1];
+        if (part.kind === 'literal' && previous?.kind === 'literal') {
+            merged[merged.length - 1] = { kind: 'literal', value: `${previous.value}${part.value}` };
+            continue;
+        }
+        merged.push(part);
+    }
+    return merged;
+}
+function validateDateFormatParts(format, parts, mode) {
+    const allowedTokens = mode === 'date' ? dateTokens : dateTimeTokens;
+    const requiredTokens = mode === 'date' ? ['yyyy', 'MM', 'dd'] : ['yyyy', 'MM', 'dd', 'HH', 'mm', 'ss'];
+    const seenTokens = new Set();
+    for (const part of parts) {
+        if (part.kind === 'literal') {
+            continue;
+        }
+        if (!allowedTokens.has(part.value)) {
+            throw createInvalidDateFormatDescriptorError(`${getFormatLabel(mode)} format "${format}" contains unsupported token "${part.value}".`);
+        }
+        if (seenTokens.has(part.value)) {
+            throw createInvalidDateFormatDescriptorError(`${getFormatLabel(mode)} format "${format}" contains duplicate token "${part.value}".`);
+        }
+        seenTokens.add(part.value);
+    }
+    for (const token of requiredTokens) {
+        if (!seenTokens.has(token)) {
+            throw createInvalidDateFormatDescriptorError(`${getFormatLabel(mode)} format "${format}" is missing required token "${token}".`);
+        }
+    }
+}
+function readDateParts(groups, compiled) {
+    return {
+        year: Number(groups.yyyy),
+        month: Number(groups.MM),
+        day: Number(groups.dd),
+        hour: compiled.mode === 'date-time' ? Number(groups.HH) : 0,
+        minute: compiled.mode === 'date-time' ? Number(groups.mm) : 0,
+        second: compiled.mode === 'date-time' ? Number(groups.ss) : 0,
+        millisecond: compiled.hasMilliseconds ? Number(groups.SSS) : 0,
+    };
+}
+function assertValidDateParts(parts, mode, options) {
+    if (parts.month < 1 ||
+        parts.month > 12 ||
+        parts.day < 1 ||
+        parts.day > 31 ||
+        parts.hour < 0 ||
+        parts.hour > 23 ||
+        parts.minute < 0 ||
+        parts.minute > 59 ||
+        parts.second < 0 ||
+        parts.second > 59 ||
+        parts.millisecond < 0 ||
+        parts.millisecond > 999) {
+        throw createDateFormatStringError(`${getFormatLabel(mode)} value must be a valid UTC calendar ${mode === 'date' ? 'date' : 'instant'}.`, options);
+    }
+}
+function matchesDateParts(value, parts) {
+    return (value.getUTCFullYear() === parts.year &&
+        value.getUTCMonth() === parts.month - 1 &&
+        value.getUTCDate() === parts.day &&
+        value.getUTCHours() === parts.hour &&
+        value.getUTCMinutes() === parts.minute &&
+        value.getUTCSeconds() === parts.second &&
+        value.getUTCMilliseconds() === parts.millisecond);
+}
+function serializeToken(input, token) {
+    switch (token) {
+        case 'yyyy':
+            return String(input.getUTCFullYear()).padStart(4, '0');
+        case 'MM':
+            return String(input.getUTCMonth() + 1).padStart(2, '0');
+        case 'dd':
+            return String(input.getUTCDate()).padStart(2, '0');
+        case 'HH':
+            return String(input.getUTCHours()).padStart(2, '0');
+        case 'mm':
+            return String(input.getUTCMinutes()).padStart(2, '0');
+        case 'ss':
+            return String(input.getUTCSeconds()).padStart(2, '0');
+        case 'SSS':
+            return String(input.getUTCMilliseconds()).padStart(3, '0');
+    }
+}
+function getTokenPattern(token) {
+    return `(?<${token}>\\d{${token === 'yyyy' || token === 'SSS' ? token.length.toString() : '2'}})`;
+}
+function escapeRegExp(value) {
+    return value.replace(/[.*+?^${}()|[\]\\]/g, '\\$&');
+}
+function isAsciiLetter(value) {
+    return /^[A-Za-z]$/.test(value);
+}
+function getFormatLabel(mode) {
+    return mode === 'date' ? 'Date' : 'Date-time';
+}
+function createDateFormatStringError(message, options) {
+    return new UrlKitError(options.code ?? 'invalid-search', message, {
+        path: [...(options.path ?? [])],
+    });
+}
+function createInvalidDateFormatDescriptorError(message) {
+    return new UrlKitError('invalid-descriptor', message);
+}
+
 const datePattern = /^(\d{4})-(\d{2})-(\d{2})$/;
 function parseDate(input, options = {}) {
     const match = datePattern.exec(input);
@@ -596,21 +800,24 @@ const unixMsCodec = {
         return serializeUnixMs(input, { code: context.errorCode, path: context.path });
     },
 };
-function date(options = {}) {
-    const format = resolveDateFormat(options);
+function date(options = {}, formatStringMode = 'date') {
+    const format = resolveDateFormat(options, formatStringMode);
     return createRuntimeSchemaBuilder({
         kind: 'date',
         options: { format },
-        codec: getDateCodec(format),
+        codec: getDateCodec(format, formatStringMode),
         validateDefault(value, context) {
             validateDateDefault(value, context);
         },
     });
 }
-function getDateCodec(format) {
+function getDateCodec(format, formatStringMode) {
     if (isDateFormatCodec(format)) {
         return createCustomDateCodec(format);
     }
+    if (isDateFormatString(format) && !isBuiltInDateFormat(format)) {
+        return createDateFormatStringCodec(format, formatStringMode);
+    }
     if (format === 'date-time') {
         return dateTimeCodec;
     }
@@ -622,6 +829,25 @@ function getDateCodec(format) {
     }
     return dateOnlyCodec;
 }
+function createDateFormatStringCodec(format, mode) {
+    return {
+        parse(input, context) {
+            return parseDateFormatString(input, format, mode, {
+                code: context.errorCode,
+                path: context.path,
+            });
+        },
+        normalize(input, context) {
+            return validateDate(input, context);
+        },
+        serialize(input, context) {
+            return serializeDateFormatString(input, format, mode, {
+                code: context.errorCode,
+                path: context.path,
+            });
+        },
+    };
+}
 function createCustomDateCodec(format) {
     return {
         parse(input, context) {
@@ -635,7 +861,7 @@ function createCustomDateCodec(format) {
         },
     };
 }
-function resolveDateFormat(options) {
+function resolveDateFormat(options, formatStringMode) {
     if (!isDateOptions(options)) {
         throw new UrlKitError('invalid-descriptor', 'Date options must be an object.');
     }
@@ -643,11 +869,18 @@ function resolveDateFormat(options) {
     if (isBuiltInDateFormat(format) || isDateFormatCodec(format)) {
         return format;
     }
-    throw new UrlKitError('invalid-descriptor', 'Date format must be a supported built-in format or an explicit codec.');
+    if (isDateFormatString(format)) {
+        validateDateFormatString(format, formatStringMode);
+        return format;
+    }
+    throw new UrlKitError('invalid-descriptor', 'Date format must be a supported built-in format, a supported format string, or an explicit codec.');
 }
 function isDateOptions(input) {
     return typeof input === 'object' && input !== null && !Array.isArray(input);
 }
+function isDateFormatString(input) {
+    return typeof input === 'string';
+}
 function isBuiltInDateFormat(input) {
     return (input === 'date' || input === 'date-time' || input === 'unix-seconds' || input === 'unix-ms');
 }
@@ -1027,19 +1260,6 @@ function isSearchSchema(input) {
     return typeof input === 'object' && input !== null && !Array.isArray(input);
 }
 
-function getPathParamKind(segment) {
-    switch (segment.constraint) {
-        case 'int':
-            return 'int';
-        case 'number':
-            return 'number';
-        case 'regex':
-            return 'regex';
-        default:
-            return 'string';
-    }
-}
-
 function assertPathMatchFailure(pattern, pathname, segments) {
     const pathnameSegments = splitPath(pathname);
     if (pathnameSegments.length !== segments.length) {
@@ -1057,55 +1277,63 @@ function assertPathMatchFailure(pattern, pathname, segments) {
             }
             continue;
         }
-        if (!isValidPathParamSegment(segment, pathnameSegment)) {
-            throw new UrlKitError('invalid-param', `Path parameter "${segment.name}" is invalid.`, {
+        const validationFailure = getPathParamValidationFailure(segment, pathnameSegment);
+        if (validationFailure) {
+            throw new UrlKitError('invalid-param', validationFailure.message, {
                 path: ['params', segment.name],
+                ...(validationFailure.cause === undefined ? {} : { cause: validationFailure.cause }),
             });
         }
     }
     throwPathMismatch(pattern, pathname);
 }
 function splitPath(pathname) {
-    if (pathname === '') {
+    if (!pathname) {
         return Object.freeze([]);
     }
     const normalized = pathname.startsWith('/') ? pathname.slice(1) : pathname;
-    if (normalized === '') {
+    if (!normalized) {
         return Object.freeze([]);
     }
     return Object.freeze(normalized.split('/'));
 }
-function isValidPathParamSegment(segment, value) {
-    if (value === '') {
-        return false;
+function getPathParamValidationFailure(segment, value) {
+    if (!value) {
+        return {
+            message: `Path parameter "${segment.name}" is invalid.`,
+        };
     }
-    const kind = getPathParamKind(segment);
-    if (kind === 'int') {
-        return /^\d+$/.test(value);
+    if (!segment.constraint) {
+        return undefined;
     }
-    if (kind === 'number') {
-        return /^-?(?:\d+(?:\.\d+)?|\.\d+)$/.test(value) && Number.isFinite(Number(value));
+    const constraint = getConstraint(segment.constraint);
+    if (!constraint) {
+        return {
+            message: `Path constraint "${segment.constraint}" is not registered.`,
+        };
     }
-    if (kind === 'regex') {
-        const params = segment.constraintParams;
-        if (!params) {
-            return false;
-        }
-        return new RegExp(`^(?:${params})$`).test(value);
+    try {
+        constraint(segment.name, value, segment.constraintParams ?? '');
+        return undefined;
     }
-    if (segment.constraint) {
-        const constraint = getConstraint(segment.constraint);
-        if (!constraint) {
-            return false;
-        }
-        try {
-            return new RegExp(`^(?:${constraint.toRegExp(segment.constraintParams ?? '')})$`).test(value);
-        }
-        catch {
-            return false;
-        }
+    catch (error) {
+        const causeMessage = getCauseMessage(error);
+        return {
+            message: causeMessage
+                ? `Path parameter "${segment.name}" is invalid: ${causeMessage}`
+                : `Path parameter "${segment.name}" is invalid.`,
+            cause: error,
+        };
+    }
+}
+function getCauseMessage(error) {
+    if (error instanceof Error && error.message) {
+        return error.message;
     }
-    return true;
+    if (typeof error === 'string' && error) {
+        return error;
+    }
+    return undefined;
 }
 function throwPathMismatch(pattern, pathname) {
     throw new UrlKitError('path-mismatch', `Pathname "${pathname}" does not match pattern "${pattern}".`, {
@@ -1113,6 +1341,24 @@ function throwPathMismatch(pattern, pathname) {
     });
 }
 
+function getPathParamKind(segment) {
+    switch (segment.constraint) {
+        case 'int':
+            return 'int';
+        case 'decimal':
+            return 'decimal';
+        case 'range':
+            return 'range';
+        case 'regex':
+            return 'regex';
+        default:
+            return 'string';
+    }
+}
+function isNumericPathParamKind(kind) {
+    return kind === 'int' || kind === 'decimal' || kind === 'range';
+}
+
 function coercePathParam(segment, value, paramsMode) {
     if (paramsMode === 'raw') {
         return value;
@@ -1127,10 +1373,10 @@ function coercePathParam(segment, value, paramsMode) {
         }
         return parsed;
     }
-    if (kind === 'number') {
+    if (isNumericPathParamKind(kind)) {
         const parsed = Number(value);
         if (!Number.isFinite(parsed)) {
-            throw new UrlKitError('invalid-param', `Path parameter "${segment.name}" must be a finite number.`, {
+            throw new UrlKitError('invalid-param', `Path parameter "${segment.name}" must be a finite decimal number.`, {
                 path: ['params', segment.name],
             });
         }
@@ -1167,79 +1413,57 @@ function isRecord(input) {
 }
 
 function parsePathPattern(pattern) {
-    if (pattern === '') {
-        return Object.freeze([]);
-    }
-    const normalized = pattern.startsWith('/') ? pattern.slice(1) : pattern;
-    if (normalized === '') {
-        return Object.freeze([]);
-    }
-    return Object.freeze(normalized.split('/').map((segment, index) => parsePathSegment(segment, index)));
-}
-function parsePathSegment(segment, index) {
-    if (!segment.startsWith('{') || !segment.endsWith('}')) {
-        return Object.freeze({ kind: 'literal', value: segment });
+    try {
+        return Object.freeze(toParsedPathSegments(tokenize(pattern)));
     }
-    const token = segment.slice(1, -1);
-    const parsed = parseParamToken(token);
-    if (!parsed.name) {
-        throw new UrlKitError('invalid-descriptor', 'Path parameter name is required.', {
-            path: ['path', String(index)],
+    catch (error) {
+        if (error instanceof UrlKitError) {
+            throw error;
+        }
+        const causeMessage = error instanceof Error && error.message ? `: ${error.message}` : '';
+        throw new UrlKitError('invalid-descriptor', `Path pattern is invalid${causeMessage}.`, {
+            path: ['path'],
+            cause: error,
         });
     }
-    return Object.freeze({ kind: 'param', ...parsed });
 }
-function parseParamToken(token) {
-    const colonIndex = token.indexOf(':');
-    if (colonIndex === -1) {
-        return { name: token };
-    }
-    const name = token.slice(0, colonIndex);
-    const constraintToken = token.slice(colonIndex + 1);
-    const paramsStart = constraintToken.indexOf('(');
-    if (paramsStart === -1 || !constraintToken.endsWith(')')) {
-        return { name, constraint: constraintToken };
+function toParsedPathSegments(tokens) {
+    const segments = [];
+    for (const token of tokens) {
+        if (token.type === 'literal') {
+            appendLiteralSegments(segments, token.value);
+            continue;
+        }
+        segments.push(toParsedParamSegment(token));
     }
-    return {
-        name,
-        constraint: constraintToken.slice(0, paramsStart),
-        constraintParams: constraintToken.slice(paramsStart + 1, -1),
-    };
+    return segments.map((segment) => Object.freeze(segment));
 }
-
-const numberConstraint = createConstraint({
-    parse(paramName, value, params) {
-        numberConstraint.verify(paramName, params);
-        const serialized = String(value);
-        if (!isFinitePathNumber(serialized)) {
-            throw new UrlKitError('invalid-param', `Path parameter "${paramName}" must be a finite number.`, {
-                path: ['params', paramName],
-            });
-        }
-    },
-    verify(paramName, params) {
-        if (params.trim()) {
-            throw new UrlKitError('invalid-descriptor', `Constraint 'number' declared for '${paramName}' parameter does not accept arguments.`, { path: ['path', paramName] });
+function appendLiteralSegments(segments, value) {
+    if (!value) {
+        return;
+    }
+    for (const segment of value.split('/')) {
+        if (!segment) {
+            continue;
         }
-    },
-    toRegExp() {
-        return '-?(?:\\d+(?:\\.\\d+)?|\\.\\d+)';
-    },
-});
-function registerUrlKitPathConstraints() {
-    if (!hasConstraint('number')) {
-        registerConstraint('number', numberConstraint);
+        segments.push({ kind: 'literal', value: segment });
     }
 }
-function isFinitePathNumber(value) {
-    if (!/^-?(?:\d+(?:\.\d+)?|\.\d+)$/.test(value)) {
-        return false;
-    }
-    return Number.isFinite(Number(value));
+function toParsedParamSegment(token) {
+    const constraint = token.constraints[0];
+    return {
+        kind: 'param',
+        name: token.name,
+        ...(constraint
+            ? {
+                constraint: constraint.type,
+                ...(constraint.params ? { constraintParams: constraint.params } : {}),
+            }
+            : {}),
+    };
 }
 
 function compilePath(pattern, options = {}) {
-    registerUrlKitPathConstraints();
     if (options.pathConstraints) {
         registerPathConstraints(options.pathConstraints);
     }
@@ -1314,5 +1538,5 @@ function compilePathPattern(pattern) {
     }
 }
 
-export { UrlKitError as U, compilePath as a, boolean as b, compileSearchSchema as c, date as d, enumOf as e, registerPathConstraints as f, handleRuntimeSchemaAbsence as g, hasPathConstraint as h, int as i, createSchemaValueError as j, createRuntimeSchemaValueContext as k, compileRuntimeSchemaValue as l, createRuntimeSchemaBuilder as m, number as n, normalizeRuntimeSchemaValue as o, getRuntimeSchemaInternals as p, runtimeSchemaSymbol as q, registerPathConstraint as r, string as s, compileRuntimeSchema as t, normalizeCompiledRuntimeSchemaValue as u, compileStaticHashDescriptor as v, parseUnixSeconds as w, parseUnixMs as x, parseDateTime as y, parseDate as z };
-//# sourceMappingURL=compile-path-wQfWAzOh.js.map
+export { parseDate as A, UrlKitError as U, compilePath as a, boolean as b, compileSearchSchema as c, date as d, enumOf as e, registerPathConstraints as f, handleRuntimeSchemaAbsence as g, hasPathConstraint as h, int as i, createSchemaValueError as j, createRuntimeSchemaValueContext as k, compileRuntimeSchemaValue as l, createRuntimeSchemaBuilder as m, number as n, normalizeRuntimeSchemaValue as o, getRuntimeSchemaInternals as p, runtimeSchemaSymbol as q, registerPathConstraint as r, string as s, compileRuntimeSchema as t, normalizeCompiledRuntimeSchemaValue as u, validateDateFormatString as v, compileStaticHashDescriptor as w, parseUnixSeconds as x, parseUnixMs as y, parseDateTime as z };
+//# sourceMappingURL=compile-path-oMMfpXR8.js.map