@craftguild/jscalendar 0.2.0 → 0.3.0

package/dist/validate/asserts.js

@@ -0,0 +1,381 @@
+import { TimeZones } from "../timezones.js";
+import { fail } from "./error.js";
+import { CHARSET_KEY, DATE_TIME, DURATION, ID_PATTERN, UTF8, Z_SUFFIX } from "./constants.js";
+import { isBooleanValue, isNumberValue, isObjectValue, isStringValue } from "../utils.js";
+const TYPEOF_UNDEFINED = "undefined";
+/**
+ * Get the UTF-8 byte length of a string.
+ * @param value Input string.
+ * @return Byte length.
+ */
+export function utf8Length(value) {
+    if (typeof TextEncoder !== TYPEOF_UNDEFINED) {
+        return new TextEncoder().encode(value).length;
+    }
+    return value.length;
+}
+/**
+ * Check whether a value is a plain record.
+ * @param value Input value.
+ * @return True if the value is a record.
+ */
+export function isRecord(value) {
+    return !!value && isObjectValue(value) && !Array.isArray(value);
+}
+/**
+ * Assert a value is a string when defined.
+ * @param value Value to check.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertString(value, path) {
+    if (value === undefined || value === null)
+        return;
+    if (!isStringValue(value))
+        fail(path, "must be a string");
+}
+/**
+ * Assert a value is a non-empty string when defined.
+ * @param value Value to check.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertNonEmptyString(value, path) {
+    if (value === undefined)
+        return;
+    if (!isStringValue(value))
+        fail(path, "must be a string");
+    if (value.length === 0)
+        fail(path, "must not be empty");
+}
+/**
+ * Assert a value is a valid Id when defined.
+ * @param value Value to check.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertId(value, path) {
+    if (value === undefined)
+        return;
+    if (!isStringValue(value))
+        fail(path, "must be an Id");
+    const length = utf8Length(value);
+    if (length < 1 || length > 255)
+        fail(path, "must be between 1 and 255 octets");
+    if (!ID_PATTERN.test(value))
+        fail(path, "must use base64url characters");
+}
+/**
+ * Assert a value is boolean when defined.
+ * @param value Value to check.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertBoolean(value, path) {
+    if (value === undefined || value === null)
+        return;
+    if (!isBooleanValue(value))
+        fail(path, "must be a boolean");
+}
+/**
+ * Assert a value is an integer when defined.
+ * @param value Value to check.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertInteger(value, path) {
+    if (value === undefined || value === null)
+        return;
+    if (!isNumberValue(value) || !Number.isInteger(value))
+        fail(path, "must be an integer");
+}
+/**
+ * Assert a value is a non-negative integer when defined.
+ * @param value Value to check.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertUnsignedInt(value, path) {
+    if (value === undefined || value === null)
+        return;
+    if (!isNumberValue(value) || !Number.isInteger(value) || value < 0) {
+        fail(path, "must be a non-negative integer");
+    }
+}
+/**
+ * Assert a date-time string matches the expected format.
+ * @param value Date-time string.
+ * @param path Validation path.
+ * @param requireZ Whether a Z suffix is required.
+ * @return Nothing.
+ */
+export function assertDateTime(value, path, requireZ) {
+    if (value === undefined)
+        return;
+    if (!isStringValue(value))
+        fail(path, "must be a date-time string");
+    const match = value.match(DATE_TIME);
+    if (!match) {
+        fail(path, requireZ ? "must be a UTCDateTime (YYYY-MM-DDTHH:mm:ssZ)" : "must be a LocalDateTime (YYYY-MM-DDTHH:mm:ss)");
+    }
+    const [, year, month, day, hour, minute, second, fraction, zFlag] = match;
+    if (requireZ && zFlag !== Z_SUFFIX)
+        fail(path, "must use Z suffix");
+    if (!requireZ && zFlag)
+        fail(path, "must not include time zone offset");
+    const monthNum = Number.parseInt(month ?? "0", 10);
+    const dayNum = Number.parseInt(day ?? "0", 10);
+    const hourNum = Number.parseInt(hour ?? "0", 10);
+    const minuteNum = Number.parseInt(minute ?? "0", 10);
+    const secondNum = Number.parseInt(second ?? "0", 10);
+    if (monthNum < 1 || monthNum > 12)
+        fail(path, "month must be 01-12");
+    if (dayNum < 1 || dayNum > 31)
+        fail(path, "day must be 01-31");
+    if (hourNum < 0 || hourNum > 23)
+        fail(path, "hour must be 00-23");
+    if (minuteNum < 0 || minuteNum > 59)
+        fail(path, "minute must be 00-59");
+    if (secondNum < 0 || secondNum > 59)
+        fail(path, "second must be 00-59");
+    if (fraction !== undefined) {
+        if (fraction.length > 9)
+            fail(path, "fractional seconds must be 1-9 digits");
+        if (/^0+$/.test(fraction))
+            fail(path, "fractional seconds must be non-zero");
+        if (fraction.endsWith("0"))
+            fail(path, "fractional seconds must not have trailing zeros");
+    }
+}
+/**
+ * Assert local date time when provided.
+ * @param value LocalDateTime string.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertLocalDateTime(value, path) {
+    return assertDateTime(value, path, false);
+}
+/**
+ * Assert utc date time when provided.
+ * @param value UTCDateTime string.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertUtcDateTime(value, path) {
+    return assertDateTime(value, path, true);
+}
+/**
+ * Assert duration like when provided.
+ * @param value Duration string.
+ * @param path Validation path.
+ * @param signed Whether negative values are allowed.
+ * @return Nothing.
+ */
+export function assertDurationLike(value, path, signed) {
+    if (value === undefined)
+        return;
+    if (!isStringValue(value))
+        fail(path, "must be a duration string");
+    if (!signed && value.startsWith("-"))
+        fail(path, "must not be negative");
+    const match = value.match(DURATION);
+    if (!match)
+        fail(path, "must be an ISO 8601 duration");
+    const week = match[1];
+    const dayFromWeek = match[2];
+    const day = match[3];
+    const hour = match[4];
+    const minute = match[5];
+    const second = match[6];
+    const fraction = match[7];
+    const hasDate = !!week || !!dayFromWeek || !!day;
+    const hasTime = !!hour || !!minute || !!second;
+    if (!hasDate && !hasTime)
+        fail(path, "must include at least one duration component");
+    if (fraction !== undefined) {
+        if (fraction.length > 9)
+            fail(path, "fractional seconds must be 1-9 digits");
+        if (/^0+$/.test(fraction))
+            fail(path, "fractional seconds must be non-zero");
+        if (fraction.endsWith("0"))
+            fail(path, "fractional seconds must not have trailing zeros");
+    }
+}
+/**
+ * Assert duration when provided.
+ * @param value Duration string.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertDuration(value, path) {
+    return assertDurationLike(value, path, false);
+}
+/**
+ * Assert signed duration when provided.
+ * @param value Duration string.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertSignedDuration(value, path) {
+    return assertDurationLike(value, path, true);
+}
+/**
+ * Assert boolean map when provided.
+ * @param value Boolean map object.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertBooleanMap(value, path) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value))
+        fail(path, "must be a boolean map object");
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry !== true)
+            fail(`${path}.${key}`, "must be true");
+    }
+}
+/**
+ * Assert ID boolean map when provided.
+ * @param value Boolean map object keyed by Ids.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertIdBooleanMap(value, path) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value))
+        fail(path, "must be a boolean map object");
+    for (const [key, entry] of Object.entries(value)) {
+        assertId(key, `${path}.${key}`);
+        if (entry !== true)
+            fail(`${path}.${key}`, "must be true");
+    }
+}
+/**
+ * Assert media type when provided.
+ * @param value Media type string.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertMediaType(value, path) {
+    if (value === undefined)
+        return;
+    if (!isStringValue(value))
+        fail(path, "must be a media type string");
+    const [typePart, ...params] = value.split(";");
+    const mediaType = (typePart ?? "").trim();
+    if (!/^[a-zA-Z0-9!#$&^_.+-]+\/[a-zA-Z0-9!#$&^_.+-]+$/.test(mediaType)) {
+        fail(path, "must be a valid media type");
+    }
+    for (const param of params) {
+        const [rawKey, rawValue] = param.split("=");
+        if (!rawKey || !rawValue)
+            continue;
+        const key = rawKey.trim().toLowerCase();
+        const valuePart = rawValue.trim().toLowerCase();
+        if (key === CHARSET_KEY && valuePart !== UTF8) {
+            fail(path, "charset parameter must be utf-8");
+        }
+    }
+}
+/**
+ * Assert text content type when provided.
+ * @param value Media type string.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertTextContentType(value, path) {
+    if (value === undefined)
+        return;
+    if (!isStringValue(value))
+        fail(path, "must be a media type string");
+    const [typePart] = value.split(";");
+    const mediaType = (typePart ?? "").trim();
+    if (!mediaType.startsWith("text/"))
+        fail(path, "must be a text/* media type");
+    assertMediaType(value, path);
+}
+/**
+ * Assert content ID when provided.
+ * @param value Content-ID string.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertContentId(value, path) {
+    if (value === undefined)
+        return;
+    if (!isStringValue(value))
+        fail(path, "must be a content-id");
+    const trimmed = value.trim();
+    const hasBrackets = trimmed.startsWith("<") || trimmed.endsWith(">");
+    if (hasBrackets && !(trimmed.startsWith("<") && trimmed.endsWith(">"))) {
+        fail(path, "must use matching angle brackets");
+    }
+    const raw = hasBrackets ? trimmed.slice(1, -1) : trimmed;
+    if (!/^[^\s<>@]+@[^\s<>@]+$/.test(raw)) {
+        fail(path, "must be a content-id");
+    }
+}
+/**
+ * Assert time zone when provided.
+ * @param value Time zone ID.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertTimeZone(value, path) {
+    if (value === undefined || value === null)
+        return;
+    if (!isStringValue(value))
+        fail(path, "must be a time zone ID");
+    for (const tz of TimeZones) {
+        if (tz === value)
+            return;
+    }
+    fail(path, "must be a supported time zone ID");
+}
+/**
+ * Assert json value when provided.
+ * @param value JSON value.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertJsonValue(value, path) {
+    if (value === undefined)
+        fail(path, "must be a JSON value");
+    if (value === null)
+        return;
+    if (isStringValue(value) || isNumberValue(value) || isBooleanValue(value))
+        return;
+    if (Array.isArray(value)) {
+        value.forEach((entry, index) => assertJsonValue(entry, `${path}[${index}]`));
+        return;
+    }
+    if (isObjectValue(value)) {
+        if (!isRecord(value))
+            fail(path, "must be a JSON object");
+        for (const [key, entry] of Object.entries(value)) {
+            assertJsonValue(entry, `${path}.${key}`);
+        }
+        return;
+    }
+    fail(path, "must be a JSON value");
+}
+/**
+ * Assert patch object when provided.
+ * @param value PatchObject.
+ * @param path Validation path.
+ * @return Nothing.
+ */
+export function assertPatchObject(value, path) {
+    if (value === undefined)
+        return;
+    if (!isRecord(value))
+        fail(path, "must be a PatchObject");
+    for (const [key, entry] of Object.entries(value)) {
+        if (entry === null)
+            continue;
+        assertJsonValue(entry, `${path}.${key}`);
+    }
+}

package/dist/validate/constants.d.ts

@@ -0,0 +1,25 @@
+export declare const Z_SUFFIX = "Z";
+export declare const CHARSET_KEY = "charset";
+export declare const UTF8 = "utf-8";
+export declare const RSCALE_GREGORIAN = "gregorian";
+export declare const TYPE_NDAY = "NDay";
+export declare const TYPE_RECURRENCE_RULE = "RecurrenceRule";
+export declare const TYPE_ALERT = "Alert";
+export declare const TYPE_OFFSET_TRIGGER = "OffsetTrigger";
+export declare const TYPE_ABSOLUTE_TRIGGER = "AbsoluteTrigger";
+export declare const TYPE_RELATION = "Relation";
+export declare const TYPE_LINK = "Link";
+export declare const TYPE_LOCATION = "Location";
+export declare const TYPE_VIRTUAL_LOCATION = "VirtualLocation";
+export declare const TYPE_TIME_ZONE_RULE = "TimeZoneRule";
+export declare const TYPE_TIME_ZONE = "TimeZone";
+export declare const TYPE_PARTICIPANT = "Participant";
+export declare const TYPE_EVENT = "Event";
+export declare const TYPE_TASK = "Task";
+export declare const TYPE_GROUP = "Group";
+export declare const DATE_TIME: RegExp;
+export declare const DURATION: RegExp;
+export declare const DAY_OF_WEEK: Set<string>;
+export declare const RECURRENCE_FREQUENCY: Set<string>;
+export declare const SKIP: Set<string>;
+export declare const ID_PATTERN: RegExp;

package/dist/validate/constants.js

@@ -0,0 +1,33 @@
+export const Z_SUFFIX = "Z";
+export const CHARSET_KEY = "charset";
+export const UTF8 = "utf-8";
+export const RSCALE_GREGORIAN = "gregorian";
+export const TYPE_NDAY = "NDay";
+export const TYPE_RECURRENCE_RULE = "RecurrenceRule";
+export const TYPE_ALERT = "Alert";
+export const TYPE_OFFSET_TRIGGER = "OffsetTrigger";
+export const TYPE_ABSOLUTE_TRIGGER = "AbsoluteTrigger";
+export const TYPE_RELATION = "Relation";
+export const TYPE_LINK = "Link";
+export const TYPE_LOCATION = "Location";
+export const TYPE_VIRTUAL_LOCATION = "VirtualLocation";
+export const TYPE_TIME_ZONE_RULE = "TimeZoneRule";
+export const TYPE_TIME_ZONE = "TimeZone";
+export const TYPE_PARTICIPANT = "Participant";
+export const TYPE_EVENT = "Event";
+export const TYPE_TASK = "Task";
+export const TYPE_GROUP = "Group";
+export const DATE_TIME = /^(\d{4})-(\d{2})-(\d{2})T(\d{2}):(\d{2}):(\d{2})(?:\.(\d+))?(Z)?$/;
+export const DURATION = /^-?P(?:(\d+)W(?:(\d+)D)?|(\d+)D)?(?:T(?:(\d+)H)?(?:(\d+)M)?(?:(\d+)(?:\.(\d+))?S)?)?$/;
+export const DAY_OF_WEEK = new Set(["mo", "tu", "we", "th", "fr", "sa", "su"]);
+export const RECURRENCE_FREQUENCY = new Set([
+    "yearly",
+    "monthly",
+    "weekly",
+    "daily",
+    "hourly",
+    "minutely",
+    "secondly",
+]);
+export const SKIP = new Set(["omit", "backward", "forward"]);
+export const ID_PATTERN = /^[A-Za-z0-9_-]+$/;

package/dist/validate/error.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Error thrown when validation fails.
+ */
+export declare class ValidationError extends Error {
+    path: string;
+    /**
+     * Create a new ValidationError.
+     * @param path Validation path.
+     * @param message Error message.
+     */
+    constructor(path: string, message: string);
+}
+/**
+ * Throw a ValidationError.
+ * @param path Validation path.
+ * @param message Error message.
+ * @return Never returns.
+ */
+export declare function fail(path: string, message: string): never;

package/dist/validate/error.js

@@ -0,0 +1,25 @@
+/**
+ * Error thrown when validation fails.
+ */
+export class ValidationError extends Error {
+    path;
+    /**
+     * Create a new ValidationError.
+     * @param path Validation path.
+     * @param message Error message.
+     */
+    constructor(path, message) {
+        super(`${path}: ${message}`);
+        this.name = "ValidationError";
+        this.path = path;
+    }
+}
+/**
+ * Throw a ValidationError.
+ * @param path Validation path.
+ * @param message Error message.
+ * @return Never returns.
+ */
+export function fail(path, message) {
+    throw new ValidationError(path, message);
+}

package/dist/validate/validators-common.d.ts

@@ -0,0 +1,64 @@
+import type { Alert, JSCalendarObject, Link, Location, Participant, Relation, TimeZone, TimeZoneRule, VirtualLocation } from "../types.js";
+/**
+ * Validate alert structure.
+ * @param value Alert object to validate.
+ * @param path JSON pointer path for error messages.
+ * @return Nothing.
+ */
+export declare function validateAlert(value: Alert, path: string): void;
+/**
+ * Validate relation structure.
+ * @param value Relation object to validate.
+ * @param path JSON pointer path for error messages.
+ * @return Nothing.
+ */
+export declare function validateRelation(value: Relation, path: string): void;
+/**
+ * Validate link structure.
+ * @param value Link object to validate.
+ * @param path JSON pointer path for error messages.
+ * @return Nothing.
+ */
+export declare function validateLink(value: Link, path: string): void;
+/**
+ * Validate location structure.
+ * @param value Location object to validate.
+ * @param path JSON pointer path for error messages.
+ * @return Nothing.
+ */
+export declare function validateLocation(value: Location, path: string): void;
+/**
+ * Validate virtual location structure.
+ * @param value VirtualLocation object to validate.
+ * @param path JSON pointer path for error messages.
+ * @return Nothing.
+ */
+export declare function validateVirtualLocation(value: VirtualLocation, path: string): void;
+/**
+ * Validate time zone rule structure.
+ * @param value TimeZoneRule object to validate.
+ * @param path JSON pointer path for error messages.
+ * @return Nothing.
+ */
+export declare function validateTimeZoneRule(value: TimeZoneRule, path: string): void;
+/**
+ * Validate time zone object structure.
+ * @param value TimeZone object to validate.
+ * @param path JSON pointer path for error messages.
+ * @return Nothing.
+ */
+export declare function validateTimeZoneObject(value: TimeZone, path: string): void;
+/**
+ * Validate participant structure.
+ * @param value Participant object to validate.
+ * @param path JSON pointer path for error messages.
+ * @return Nothing.
+ */
+export declare function validateParticipant(value: Participant, path: string): void;
+/**
+ * Validate common structure.
+ * @param value JSCalendar object to validate.
+ * @param path JSON pointer path for error messages.
+ * @return Nothing.
+ */
+export declare function validateCommon(value: JSCalendarObject, path: string): void;