@craftguild/jscalendar 0.3.0 → 0.4.0

package/README.md

@@ -100,7 +100,7 @@ const task = new JsCal.Task({
     JsCal.Location({ name: "Room A" }),
   ]),
   alerts: JsCal.alerts([
-    JsCal.Alert({ trigger: { "@type": "OffsetTrigger", offset: "-PT15M" } }),
+    JsCal.Alert({ trigger: JsCal.OffsetTrigger({ offset: JsCal.duration.minutes(-15) }) }),
   ]),
 });
 ```

package/dist/__tests__/builders.test.js

@@ -1,6 +1,6 @@
 import { describe, expect, it } from "vitest";
 import { JsCal } from "../jscal.js";
-import { buildAlert, buildIdMap, buildLink, buildLocation, buildNDay, buildRecurrenceRule, buildRelation, buildTimeZone, buildTimeZoneMap, buildTimeZoneRule, buildVirtualLocation, } from "../jscal/builders.js";
+import { buildAbsoluteTrigger, buildAlert, buildIdMap, buildLink, buildLocation, buildNDay, buildOffsetTrigger, buildRecurrenceRule, buildRelation, buildTimeZone, buildTimeZoneMap, buildTimeZoneRule, buildVirtualLocation, } from "../jscal/builders.js";
 describe("builders", () => {
     it("builds strict objects with @type", () => {
         const participant = JsCal.Participant({ name: "Alice", roles: { attendee: true } });
@@ -8,7 +8,8 @@ describe("builders", () => {
         const vloc = buildVirtualLocation({ name: "Zoom", uri: "https://example.com" });
         const link = buildLink({ href: "https://example.com" });
         const relation = buildRelation({ relation: { parent: true } });
-        const alert = buildAlert({ trigger: { "@type": "OffsetTrigger", offset: "-PT15M" } });
+        const alert = buildAlert({ trigger: buildOffsetTrigger({ offset: JsCal.duration.minutes(-15) }) });
+        const absoluteTrigger = buildAbsoluteTrigger({ when: "2026-02-01T00:00:00Z" });
         const nday = buildNDay({ day: "mo" });
         const rule = buildRecurrenceRule({ frequency: "daily" });
         const tzRule = buildTimeZoneRule({
@@ -26,6 +27,7 @@ describe("builders", () => {
         expect(link["@type"]).toBe("Link");
         expect(relation["@type"]).toBe("Relation");
         expect(alert["@type"]).toBe("Alert");
+        expect(absoluteTrigger["@type"]).toBe("AbsoluteTrigger");
         expect(nday["@type"]).toBe("NDay");
         expect(rule["@type"]).toBe("RecurrenceRule");
         expect(tz["@type"]).toBe("TimeZone");
@@ -66,6 +68,10 @@ describe("builders", () => {
             .toThrowError("virtualLocation: must have @type VirtualLocation");
         expect(() => buildAlert({ "@type": "Link" }))
             .toThrowError("alert: must have @type Alert");
+        expect(() => buildOffsetTrigger({ "@type": "Alert" }))
+            .toThrowError("offsetTrigger: must have @type OffsetTrigger");
+        expect(() => buildAbsoluteTrigger({ "@type": "Alert" }))
+            .toThrowError("absoluteTrigger: must have @type AbsoluteTrigger");
         expect(() => buildRelation({ "@type": "Link" }))
             .toThrowError("relation: must have @type Relation");
         expect(() => buildLink({ "@type": "Relation" }))

package/dist/__tests__/utils.test.js

@@ -49,6 +49,14 @@ describe("utils", () => {
         expect(JsCal.duration.days(1)).toBe("P1D");
         expect(JsCal.duration.from({ hours: 1, minutes: 15 })).toBe("PT1H15M");
     });
+    it("builds signed duration strings for negative values", () => {
+        expect(JsCal.duration.minutes(-15)).toBe("-PT15M");
+        expect(JsCal.duration.seconds(-1)).toBe("-PT1S");
+        expect(JsCal.duration.from({ minutes: -15 })).toBe("-PT15M");
+    });
+    it("avoids negative zero in duration strings", () => {
+        expect(JsCal.duration.seconds(-0)).toBe("PT0S");
+    });
     it("creates base64url ids", () => {
         const id = JsCal.createId();
         expect(id).toMatch(/^[A-Za-z0-9_-]+$/);

package/dist/jscal/builders.d.ts

@@ -1,8 +1,10 @@
-import type { Alert, Link, Location, NDay, Participant, RecurrenceRule, Relation, TimeZone, TimeZoneRule, VirtualLocation, Id } from "../types.js";
+import type { Alert, AbsoluteTrigger, Link, Location, NDay, OffsetTrigger, Participant, RecurrenceRule, Relation, TimeZone, TimeZoneRule, VirtualLocation, Id } from "../types.js";
 declare const TYPE_PARTICIPANT = "Participant";
 declare const TYPE_LOCATION = "Location";
 declare const TYPE_VIRTUAL_LOCATION = "VirtualLocation";
 declare const TYPE_ALERT = "Alert";
+declare const TYPE_OFFSET_TRIGGER = "OffsetTrigger";
+declare const TYPE_ABSOLUTE_TRIGGER = "AbsoluteTrigger";
 declare const TYPE_RELATION = "Relation";
 declare const TYPE_LINK = "Link";
 declare const TYPE_TIME_ZONE = "TimeZone";
@@ -16,6 +18,8 @@ export type ParticipantInput = WithOptionalType<Participant, typeof TYPE_PARTICI
 export type LocationInput = WithOptionalType<Location, typeof TYPE_LOCATION>;
 export type VirtualLocationInput = WithOptionalType<VirtualLocation, typeof TYPE_VIRTUAL_LOCATION>;
 export type AlertInput = WithOptionalType<Alert, typeof TYPE_ALERT>;
+export type OffsetTriggerInput = WithOptionalType<OffsetTrigger, typeof TYPE_OFFSET_TRIGGER>;
+export type AbsoluteTriggerInput = WithOptionalType<AbsoluteTrigger, typeof TYPE_ABSOLUTE_TRIGGER>;
 export type RelationInput = WithOptionalType<Relation, typeof TYPE_RELATION>;
 export type LinkInput = WithOptionalType<Link, typeof TYPE_LINK>;
 export type TimeZoneInput = WithOptionalType<TimeZone, typeof TYPE_TIME_ZONE>;
@@ -46,6 +50,18 @@ export declare function buildVirtualLocation(input: VirtualLocationInput): Virtu
  * @return Validated Alert object.
  */
 export declare function buildAlert(input: AlertInput): Alert;
+/**
+ * Build an OffsetTrigger object with @type set and validated.
+ * @param input OffsetTrigger fields without @type.
+ * @return Validated OffsetTrigger object.
+ */
+export declare function buildOffsetTrigger(input: OffsetTriggerInput): OffsetTrigger;
+/**
+ * Build an AbsoluteTrigger object with @type set and validated.
+ * @param input AbsoluteTrigger fields without @type.
+ * @return Validated AbsoluteTrigger object.
+ */
+export declare function buildAbsoluteTrigger(input: AbsoluteTriggerInput): AbsoluteTrigger;
 /**
  * Build a Relation object with @type set and validated.
  * @param input Relation fields without @type.

package/dist/jscal/builders.js

@@ -2,10 +2,13 @@ import { createId } from "./ids.js";
 import { validateAlert, validateLink, validateLocation, validateParticipant, validateRelation, validateTimeZoneObject, validateTimeZoneRule, validateVirtualLocation } from "../validate/validators-common.js";
 import { validateNDay, validateRecurrenceRule } from "../validate/validators-recurrence.js";
 import { fail } from "../validate/error.js";
+import { assertSignedDuration, assertString, assertUtcDateTime } from "../validate/asserts.js";
 const TYPE_PARTICIPANT = "Participant";
 const TYPE_LOCATION = "Location";
 const TYPE_VIRTUAL_LOCATION = "VirtualLocation";
 const TYPE_ALERT = "Alert";
+const TYPE_OFFSET_TRIGGER = "OffsetTrigger";
+const TYPE_ABSOLUTE_TRIGGER = "AbsoluteTrigger";
 const TYPE_RELATION = "Relation";
 const TYPE_LINK = "Link";
 const TYPE_TIME_ZONE = "TimeZone";
@@ -64,6 +67,33 @@ export function buildAlert(input) {
     validateAlert(alert, "alert");
     return alert;
 }
+/**
+ * Build an OffsetTrigger object with @type set and validated.
+ * @param input OffsetTrigger fields without @type.
+ * @return Validated OffsetTrigger object.
+ */
+export function buildOffsetTrigger(input) {
+    if (input["@type"] && input["@type"] !== TYPE_OFFSET_TRIGGER) {
+        fail("offsetTrigger", `must have @type ${TYPE_OFFSET_TRIGGER}`);
+    }
+    const trigger = { ...input, "@type": TYPE_OFFSET_TRIGGER };
+    assertSignedDuration(trigger.offset, "offsetTrigger.offset");
+    assertString(trigger.relativeTo, "offsetTrigger.relativeTo");
+    return trigger;
+}
+/**
+ * Build an AbsoluteTrigger object with @type set and validated.
+ * @param input AbsoluteTrigger fields without @type.
+ * @return Validated AbsoluteTrigger object.
+ */
+export function buildAbsoluteTrigger(input) {
+    if (input["@type"] && input["@type"] !== TYPE_ABSOLUTE_TRIGGER) {
+        fail("absoluteTrigger", `must have @type ${TYPE_ABSOLUTE_TRIGGER}`);
+    }
+    const trigger = { ...input, "@type": TYPE_ABSOLUTE_TRIGGER };
+    assertUtcDateTime(trigger.when, "absoluteTrigger.when");
+    return trigger;
+}
 /**
  * Build a Relation object with @type set and validated.
  * @param input Relation fields without @type.

package/dist/jscal/duration.d.ts

@@ -8,31 +8,31 @@ export declare const Duration: {
     /**
      * Convert seconds to a duration string.
      * @param value Total seconds.
-     * @return ISO 8601 duration string.
+     * @return ISO 8601 duration string (signed when negative).
      */
     seconds(value: number): string;
     /**
      * Convert minutes to a duration string.
      * @param value Total minutes.
-     * @return ISO 8601 duration string.
+     * @return ISO 8601 duration string (signed when negative).
      */
     minutes(value: number): string;
     /**
      * Convert hours to a duration string.
      * @param value Total hours.
-     * @return ISO 8601 duration string.
+     * @return ISO 8601 duration string (signed when negative).
      */
     hours(value: number): string;
     /**
      * Convert days to a duration string.
      * @param value Total days.
-     * @return ISO 8601 duration string.
+     * @return ISO 8601 duration string (signed when negative).
      */
     days(value: number): string;
     /**
      * Build a duration string from component parts.
      * @param parts Day/hour/minute/second parts.
-     * @return ISO 8601 duration string.
+     * @return ISO 8601 duration string (signed when total is negative).
      */
     from(parts: {
         days?: number;

package/dist/jscal/duration.js

@@ -5,7 +5,9 @@ import { EMPTY_STRING } from "./constants.js";
  * @return ISO 8601 duration string.
  */
 export function durationFromSeconds(totalSeconds) {
-    const clamped = Math.max(0, Math.floor(totalSeconds));
+    const negative = totalSeconds < 0;
+    const absSeconds = Math.abs(totalSeconds);
+    const clamped = Math.floor(absSeconds);
     const days = Math.floor(clamped / 86400);
     let remaining = clamped % 86400;
     const hours = Math.floor(remaining / 3600);
@@ -22,13 +24,14 @@ export function durationFromSeconds(totalSeconds) {
         timeParts.push(`${seconds}S`);
     }
     const timePart = timeParts.length > 0 ? `T${timeParts.join("")}` : "";
-    return `P${datePart}${timePart}`;
+    const sign = negative && clamped > 0 ? "-" : "";
+    return `${sign}P${datePart}${timePart}`;
 }
 export const Duration = {
     /**
      * Convert seconds to a duration string.
      * @param value Total seconds.
-     * @return ISO 8601 duration string.
+     * @return ISO 8601 duration string (signed when negative).
      */
     seconds(value) {
         return durationFromSeconds(value);
@@ -36,7 +39,7 @@ export const Duration = {
     /**
      * Convert minutes to a duration string.
      * @param value Total minutes.
-     * @return ISO 8601 duration string.
+     * @return ISO 8601 duration string (signed when negative).
      */
     minutes(value) {
         return durationFromSeconds(value * 60);
@@ -44,7 +47,7 @@ export const Duration = {
     /**
      * Convert hours to a duration string.
      * @param value Total hours.
-     * @return ISO 8601 duration string.
+     * @return ISO 8601 duration string (signed when negative).
      */
     hours(value) {
         return durationFromSeconds(value * 3600);
@@ -52,7 +55,7 @@ export const Duration = {
     /**
      * Convert days to a duration string.
      * @param value Total days.
-     * @return ISO 8601 duration string.
+     * @return ISO 8601 duration string (signed when negative).
      */
     days(value) {
         return durationFromSeconds(value * 86400);
@@ -60,7 +63,7 @@ export const Duration = {
     /**
      * Build a duration string from component parts.
      * @param parts Day/hour/minute/second parts.
-     * @return ISO 8601 duration string.
+     * @return ISO 8601 duration string (signed when total is negative).
      */
     from(parts) {
         const seconds = (parts.days ?? 0) * 86400 +

package/dist/jscal/event.js

@@ -43,7 +43,7 @@ export class EventObject extends Base {
             data.timeZone = timeZone;
         if (rawDuration !== undefined) {
             data.duration = isNumberValue(rawDuration)
-                ? durationFromSeconds(rawDuration)
+                ? durationFromSeconds(Math.max(0, rawDuration))
                 : rawDuration;
         }
         if (rawCreated) {

package/dist/jscal.d.ts

@@ -6,9 +6,9 @@ import { TaskObject } from "./jscal/task.js";
 import { GroupObject } from "./jscal/group.js";
 import { createId, createUid } from "./jscal/ids.js";
 import { isEvent, isGroup, isTask } from "./jscal/guards.js";
-import { buildAlert, buildLink, buildLocation, buildNDay, buildParticipants, buildRecurrenceRule, buildRelation, buildRelatedTo, buildTimeZone, buildTimeZoneMap, buildTimeZoneRule, buildVirtualLocation, buildVirtualLocations, buildLocations, buildLinks, buildParticipant, buildAlerts } from "./jscal/builders.js";
+import { buildAlert, buildAbsoluteTrigger, buildLink, buildLocation, buildNDay, buildOffsetTrigger, buildParticipants, buildRecurrenceRule, buildRelation, buildRelatedTo, buildTimeZone, buildTimeZoneMap, buildTimeZoneRule, buildVirtualLocation, buildVirtualLocations, buildLocations, buildLinks, buildParticipant, buildAlerts } from "./jscal/builders.js";
 export type { CreateOptions, UpdateOptions } from "./jscal/types.js";
-export type { AlertInput, LinkInput, LocationInput, NDayInput, ParticipantInput, RecurrenceRuleInput, RelationInput, TimeZoneInput, TimeZoneRuleInput, VirtualLocationInput, } from "./jscal/builders.js";
+export type { AlertInput, AbsoluteTriggerInput, LinkInput, LocationInput, NDayInput, OffsetTriggerInput, ParticipantInput, RecurrenceRuleInput, RelationInput, TimeZoneInput, TimeZoneRuleInput, VirtualLocationInput, } from "./jscal/builders.js";
 export { createId, createUid, isEvent, isGroup, isTask };
 export declare const JsCal: {
     Event: typeof EventObject;
@@ -35,6 +35,8 @@ export declare const JsCal: {
     Location: typeof buildLocation;
     VirtualLocation: typeof buildVirtualLocation;
     Alert: typeof buildAlert;
+    OffsetTrigger: typeof buildOffsetTrigger;
+    AbsoluteTrigger: typeof buildAbsoluteTrigger;
     Relation: typeof buildRelation;
     Link: typeof buildLink;
     TimeZone: typeof buildTimeZone;

package/dist/jscal.js

@@ -10,7 +10,7 @@ import { Duration } from "./jscal/duration.js";
 import { createId, createUid } from "./jscal/ids.js";
 import { normalizeItems, normalizeToObjects } from "./jscal/normalize.js";
 import { isEvent, isGroup, isTask } from "./jscal/guards.js";
-import { buildAlert, buildLink, buildLocation, buildNDay, buildParticipants, buildRecurrenceRule, buildRelation, buildRelatedTo, buildTimeZone, buildTimeZoneMap, buildTimeZoneRule, buildVirtualLocation, buildVirtualLocations, buildLocations, buildLinks, buildParticipant, buildAlerts, } from "./jscal/builders.js";
+import { buildAlert, buildAbsoluteTrigger, buildLink, buildLocation, buildNDay, buildOffsetTrigger, buildParticipants, buildRecurrenceRule, buildRelation, buildRelatedTo, buildTimeZone, buildTimeZoneMap, buildTimeZoneRule, buildVirtualLocation, buildVirtualLocations, buildLocations, buildLinks, buildParticipant, buildAlerts, } from "./jscal/builders.js";
 export { createId, createUid, isEvent, isGroup, isTask };
 export const JsCal = {
     Event: EventObject,
@@ -26,6 +26,8 @@ export const JsCal = {
     Location: buildLocation,
     VirtualLocation: buildVirtualLocation,
     Alert: buildAlert,
+    OffsetTrigger: buildOffsetTrigger,
+    AbsoluteTrigger: buildAbsoluteTrigger,
     Relation: buildRelation,
     Link: buildLink,
     TimeZone: buildTimeZone,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@craftguild/jscalendar",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "description": "RFC 8984 (JSCalendar) data model helpers for TypeScript",
   "type": "module",
   "main": "dist/index.js",