@craftguild/jscalendar 0.5.6 → 0.6.0

package/README.md

@@ -31,7 +31,7 @@ pnpm add @craftguild/jscalendar
 
 You can also load the library directly in the browser from `esm.sh`.
 The repository includes a single-file example at
-`examples/esm-browser-demo.html` that demonstrates:
+[`examples/browser/demo.html`](./examples/browser/demo.html) that demonstrates:
 
 - toggling between `Event` and `Task`
 - defining recurrence rules and expanding them within a date range
@@ -39,7 +39,7 @@ The repository includes a single-file example at
 
 ```html
 <script type="module">
-    import { JsCal } from "https://esm.sh/@craftguild/jscalendar@0.5.6?bundle";
+    import { JsCal } from "https://esm.sh/@craftguild/jscalendar@0.6.0?bundle";
 
     const event = new JsCal.Event({
         title: "Browser demo",
@@ -76,6 +76,11 @@ const task = new JsCal.Task({
 const from = new Date(2026, 0, 1, 0, 0, 0, 0);
 const to = new Date(2026, 0, 31, 0, 0, 0, 0);
 const generator = JsCal.expandRecurrence([event, task], { from, to });
+const withoutAnchor = JsCal.expandRecurrence(
+    [event],
+    { from, to },
+    { includeAnchor: false },
+);
 
 for (const item of generator) {
     // Expanded JSCalendar objects for events and tasks in the range.
@@ -378,6 +383,9 @@ The recurrence expansion API is a generator.
 Expansion follows RFC 8984 semantics for recurrence rules, including
 overrides and exclusions. The output instances contain `recurrenceId`
 and preserve the base object’s data unless a patch modifies fields.
+By default, the source item’s anchor occurrence is included to preserve
+backward compatibility. Pass `{ includeAnchor: false }` to exclude the
+source anchor and return only rule-expanded occurrences.
 
 ```ts
 for (const occ of JsCal.expandRecurrence([event], {
@@ -386,6 +394,14 @@ for (const occ of JsCal.expandRecurrence([event], {
 })) {
     console.log(occ);
 }
+
+for (const occ of JsCal.expandRecurrence(
+    [event],
+    { from: new Date("2026-02-01"), to: new Date("2026-03-01") },
+    { includeAnchor: false },
+)) {
+    console.log(occ);
+}
 ```
 
 ### Paged Expansion (for infinite scroll)

package/dist/index.cjs

@@ -1025,7 +1025,7 @@ function generateDateCandidates(periodStart, rule, firstDay, skip) {
 		return result;
 	}
 	if (rule.frequency === FREQ_WEEKLY) {
-		let cursor = periodStart;
+		let cursor = startOfWeek(periodStart, firstDay);
 		for (let i = 0; i < 7; i += 1) {
 			result.push({
 				year: cursor.year,
@@ -1259,10 +1259,12 @@ function expandRule(anchor, rule, fromLocal, toLocal, includeAnchor, timeZone, f
 	const results = [];
 	let generated = 0;
 	let cursor = start;
+	const anchorValue = formatLocalDateTime(start);
 	while (generated < count) {
 		let filtered = generateDateTimes(cursor, normalized, firstDay, skip).sort();
 		if (normalized.bySetPosition && normalized.bySetPosition.length > 0) filtered = applyBySetPos(filtered, normalized.bySetPosition);
 		for (const dt of filtered) {
+			if (compareDate(cursor, start) === 0 && dt < anchorValue) continue;
 			generated += 1;
 			if (generated > count) break;
 			if (until && dt > until) return results;
@@ -1282,14 +1284,17 @@ function expandRule(anchor, rule, fromLocal, toLocal, includeAnchor, timeZone, f
 * Expand recurrence into occurrences sorted by recurrenceId/start.
 * @param items JSCalendar objects to expand.
 * @param range Date range bounds.
+* @param options Expansion options.
 * @return Generator of expanded occurrences.
 */
-function* expandRecurrence(items, range) {
+function* expandRecurrence(items, range, options = {}) {
+	var _options$includeAncho;
 	const occurrences = [];
 	let index = 0;
+	const includeAnchor = (_options$includeAncho = options.includeAnchor) !== null && _options$includeAncho !== void 0 ? _options$includeAncho : true;
 	for (const item of items) {
 		if (item["@type"] === TYPE_EVENT$3) {
-			for (const occurrence of expandEvent(item, range)) {
+			for (const occurrence of expandEvent(item, range, includeAnchor)) {
 				occurrences.push({
 					value: occurrence,
 					key: occurrenceKey(occurrence),
@@ -1300,7 +1305,7 @@ function* expandRecurrence(items, range) {
 			continue;
 		}
 		if (item["@type"] === TYPE_TASK$3) {
-			for (const occurrence of expandTask(item, range)) {
+			for (const occurrence of expandTask(item, range, includeAnchor)) {
 				occurrences.push({
 					value: occurrence,
 					key: occurrenceKey(occurrence),
@@ -1335,7 +1340,7 @@ function* expandRecurrence(items, range) {
 function expandRecurrencePaged(items, range, options) {
 	const result = [];
 	let nextCursor;
-	for (const occurrence of expandRecurrence(items, range)) {
+	for (const occurrence of expandRecurrence(items, range, options)) {
 		const key = occurrenceKey(occurrence);
 		if (options.cursor && key) {
 			if (key <= options.cursor) continue;
@@ -1353,23 +1358,25 @@ function expandRecurrencePaged(items, range, options) {
 * Expand event into occurrences.
 * @param event Event to expand.
 * @param range Date range bounds.
+* @param includeAnchor Whether the source event should be included.
 * @return Generator of expanded occurrences.
 */
-function expandEvent(event, range) {
+function expandEvent(event, range, includeAnchor) {
 	var _event$timeZone;
-	return expandObject(event, range, event.start, event.recurrenceRules, event.excludedRecurrenceRules, event.recurrenceOverrides, (_event$timeZone = event.timeZone) !== null && _event$timeZone !== void 0 ? _event$timeZone : null);
+	return expandObject(event, range, event.start, event.recurrenceRules, event.excludedRecurrenceRules, event.recurrenceOverrides, (_event$timeZone = event.timeZone) !== null && _event$timeZone !== void 0 ? _event$timeZone : null, includeAnchor);
 }
 /**
 * Expand task into occurrences.
 * @param task Task to expand.
 * @param range Date range bounds.
+* @param includeAnchor Whether the source task should be included.
 * @return Generator of expanded occurrences.
 */
-function expandTask(task, range) {
+function expandTask(task, range, includeAnchor) {
 	var _task$start, _task$timeZone;
 	const anchor = (_task$start = task.start) !== null && _task$start !== void 0 ? _task$start : task.due;
 	if (!anchor) return (function* empty() {})();
-	return expandObject(task, range, anchor, task.recurrenceRules, task.excludedRecurrenceRules, task.recurrenceOverrides, (_task$timeZone = task.timeZone) !== null && _task$timeZone !== void 0 ? _task$timeZone : null);
+	return expandObject(task, range, anchor, task.recurrenceRules, task.excludedRecurrenceRules, task.recurrenceOverrides, (_task$timeZone = task.timeZone) !== null && _task$timeZone !== void 0 ? _task$timeZone : null, includeAnchor);
 }
 /**
 * Build a stable ordering key for an occurrence.
@@ -1391,9 +1398,10 @@ function occurrenceKey(value) {
 * @param excludedRules Exclusion recurrence rules.
 * @param overrides Recurrence overrides keyed by LocalDateTime.
 * @param recurrenceIdTimeZone Optional time zone for recurrence IDs.
+* @param includeAnchor Whether the source item should be included.
 * @return Generator of expanded occurrences.
 */
-function* expandObject(base, range, anchor, rules, excludedRules, overrides, recurrenceIdTimeZone) {
+function* expandObject(base, range, anchor, rules, excludedRules, overrides, recurrenceIdTimeZone, includeAnchor = true) {
 	var _rules$;
 	const hasZone = Boolean(recurrenceIdTimeZone);
 	const fromLocal = hasZone && recurrenceIdTimeZone ? dateTimeInTimeZone(range.from, recurrenceIdTimeZone) : localDateTimeFromDate(range.from);
@@ -1402,9 +1410,11 @@ function* expandObject(base, range, anchor, rules, excludedRules, overrides, rec
 	const toDate = range.to;
 	const overrideKeys = overrides ? Object.keys(overrides) : [];
 	if (!rules || rules.length === 0) {
-		if (hasZone && recurrenceIdTimeZone) {
-			if (isInRangeWithZone(anchor, fromDate, toDate, recurrenceIdTimeZone)) yield base;
-		} else if (isInRange(anchor, fromLocal, toLocal)) yield base;
+		if (includeAnchor) {
+			if (hasZone && recurrenceIdTimeZone) {
+				if (isInRangeWithZone(anchor, fromDate, toDate, recurrenceIdTimeZone)) yield base;
+			} else if (isInRange(anchor, fromLocal, toLocal)) yield base;
+		}
 		for (const key of overrideKeys) {
 			const instance = buildInstance(base, key, recurrenceIdTimeZone, overrides ? overrides[key] : void 0);
 			if (!instance) continue;
@@ -1424,11 +1434,12 @@ function* expandObject(base, range, anchor, rules, excludedRules, overrides, rec
 		const expanded = expandRule(anchor, rule, fromLocal, toLocal, true, recurrenceIdTimeZone !== null && recurrenceIdTimeZone !== void 0 ? recurrenceIdTimeZone : void 0, fromDate, toDate);
 		for (const value of expanded) excluded.add(value);
 	}
-	if (!occurrences.includes(anchor)) occurrences.push(anchor);
+	if (includeAnchor && !occurrences.includes(anchor)) occurrences.push(anchor);
 	for (const key of overrideKeys) if (!occurrences.includes(key)) occurrences.push(key);
 	let sorted = Array.from(new Set(occurrences)).sort((a, b) => compareLocal(a, b, recurrenceIdTimeZone !== null && recurrenceIdTimeZone !== void 0 ? recurrenceIdTimeZone : void 0));
 	if (((_rules$ = rules[0]) === null || _rules$ === void 0 ? void 0 : _rules$.count) && sorted.length > rules[0].count) sorted = sorted.slice(0, rules[0].count);
 	for (const dt of sorted) {
+		if (!includeAnchor && dt === anchor) continue;
 		if (excluded.has(dt)) continue;
 		const instance = buildInstance(base, dt, recurrenceIdTimeZone, overrides ? overrides[dt] : void 0);
 		if (!instance) continue;
@@ -3950,8 +3961,8 @@ const JsCal = {
 	filterByDateRange(items, range, options) {
 		return filterByDateRange(normalizeItems(items), range, options);
 	},
-	expandRecurrence(items, range) {
-		return expandRecurrence(normalizeItems(items), range);
+	expandRecurrence(items, range, options) {
+		return expandRecurrence(normalizeItems(items), range, options);
 	},
 	expandRecurrencePaged(items, range, options) {
 		return expandRecurrencePaged(normalizeItems(items), range, options);

package/dist/index.d.cts

@@ -263,6 +263,15 @@ type DateRangeOptions = {
   includeIncomparable?: boolean;
 };
 //#endregion
+//#region src/recurrence/types.d.ts
+type RecurrenceExpandOptions = {
+  includeAnchor?: boolean;
+};
+type RecurrencePageOptions = RecurrenceExpandOptions & {
+  limit: number;
+  cursor?: string;
+};
+//#endregion
 //#region src/ical.d.ts
 type ICalOptions = {
   prodId?: string;
@@ -748,6 +757,7 @@ declare const JsCal: {
    * Expand recurrence rules into concrete occurrences.
    * @param items JSCalendar objects or JsCal instances.
    * @param range Date range bounds.
+   * @param options Expansion options.
    * @return Generator of expanded JSCalendar objects.
    */
   expandRecurrence(items: Array<JSCalendarObject | {
@@ -755,7 +765,7 @@ declare const JsCal: {
   }>, range: {
     from: Date;
     to: Date;
-  }): Generator<JSCalendarObject>;
+  }, options?: RecurrenceExpandOptions): Generator<JSCalendarObject>;
   /**
    * Expand recurrence rules with pagination support.
    * @param items JSCalendar objects or JsCal instances.
@@ -768,10 +778,7 @@ declare const JsCal: {
   }>, range: {
     from: Date;
     to: Date;
-  }, options: {
-    limit: number;
-    cursor?: string | undefined;
-  }): {
+  }, options: RecurrencePageOptions): {
     items: JSCalendarObject[];
     nextCursor?: string;
   };

package/dist/index.d.mts

@@ -263,6 +263,15 @@ type DateRangeOptions = {
   includeIncomparable?: boolean;
 };
 //#endregion
+//#region src/recurrence/types.d.ts
+type RecurrenceExpandOptions = {
+  includeAnchor?: boolean;
+};
+type RecurrencePageOptions = RecurrenceExpandOptions & {
+  limit: number;
+  cursor?: string;
+};
+//#endregion
 //#region src/ical.d.ts
 type ICalOptions = {
   prodId?: string;
@@ -748,6 +757,7 @@ declare const JsCal: {
    * Expand recurrence rules into concrete occurrences.
    * @param items JSCalendar objects or JsCal instances.
    * @param range Date range bounds.
+   * @param options Expansion options.
    * @return Generator of expanded JSCalendar objects.
    */
   expandRecurrence(items: Array<JSCalendarObject | {
@@ -755,7 +765,7 @@ declare const JsCal: {
   }>, range: {
     from: Date;
     to: Date;
-  }): Generator<JSCalendarObject>;
+  }, options?: RecurrenceExpandOptions): Generator<JSCalendarObject>;
   /**
    * Expand recurrence rules with pagination support.
    * @param items JSCalendar objects or JsCal instances.
@@ -768,10 +778,7 @@ declare const JsCal: {
   }>, range: {
     from: Date;
     to: Date;
-  }, options: {
-    limit: number;
-    cursor?: string | undefined;
-  }): {
+  }, options: RecurrencePageOptions): {
     items: JSCalendarObject[];
     nextCursor?: string;
   };

package/dist/index.mjs

@@ -1019,7 +1019,7 @@ function generateDateCandidates(periodStart, rule, firstDay, skip) {
 		return result;
 	}
 	if (rule.frequency === FREQ_WEEKLY) {
-		let cursor = periodStart;
+		let cursor = startOfWeek(periodStart, firstDay);
 		for (let i = 0; i < 7; i += 1) {
 			result.push({
 				year: cursor.year,
@@ -1252,10 +1252,12 @@ function expandRule(anchor, rule, fromLocal, toLocal, includeAnchor, timeZone, f
 	const results = [];
 	let generated = 0;
 	let cursor = start;
+	const anchorValue = formatLocalDateTime(start);
 	while (generated < count) {
 		let filtered = generateDateTimes(cursor, normalized, firstDay, skip).sort();
 		if (normalized.bySetPosition && normalized.bySetPosition.length > 0) filtered = applyBySetPos(filtered, normalized.bySetPosition);
 		for (const dt of filtered) {
+			if (compareDate(cursor, start) === 0 && dt < anchorValue) continue;
 			generated += 1;
 			if (generated > count) break;
 			if (until && dt > until) return results;
@@ -1275,14 +1277,16 @@ function expandRule(anchor, rule, fromLocal, toLocal, includeAnchor, timeZone, f
 * Expand recurrence into occurrences sorted by recurrenceId/start.
 * @param items JSCalendar objects to expand.
 * @param range Date range bounds.
+* @param options Expansion options.
 * @return Generator of expanded occurrences.
 */
-function* expandRecurrence(items, range) {
+function* expandRecurrence(items, range, options = {}) {
 	const occurrences = [];
 	let index = 0;
+	const includeAnchor = options.includeAnchor ?? true;
 	for (const item of items) {
 		if (item["@type"] === TYPE_EVENT$3) {
-			for (const occurrence of expandEvent(item, range)) {
+			for (const occurrence of expandEvent(item, range, includeAnchor)) {
 				occurrences.push({
 					value: occurrence,
 					key: occurrenceKey(occurrence),
@@ -1293,7 +1297,7 @@ function* expandRecurrence(items, range) {
 			continue;
 		}
 		if (item["@type"] === TYPE_TASK$3) {
-			for (const occurrence of expandTask(item, range)) {
+			for (const occurrence of expandTask(item, range, includeAnchor)) {
 				occurrences.push({
 					value: occurrence,
 					key: occurrenceKey(occurrence),
@@ -1328,7 +1332,7 @@ function* expandRecurrence(items, range) {
 function expandRecurrencePaged(items, range, options) {
 	const result = [];
 	let nextCursor;
-	for (const occurrence of expandRecurrence(items, range)) {
+	for (const occurrence of expandRecurrence(items, range, options)) {
 		const key = occurrenceKey(occurrence);
 		if (options.cursor && key) {
 			if (key <= options.cursor) continue;
@@ -1346,21 +1350,23 @@ function expandRecurrencePaged(items, range, options) {
 * Expand event into occurrences.
 * @param event Event to expand.
 * @param range Date range bounds.
+* @param includeAnchor Whether the source event should be included.
 * @return Generator of expanded occurrences.
 */
-function expandEvent(event, range) {
-	return expandObject(event, range, event.start, event.recurrenceRules, event.excludedRecurrenceRules, event.recurrenceOverrides, event.timeZone ?? null);
+function expandEvent(event, range, includeAnchor) {
+	return expandObject(event, range, event.start, event.recurrenceRules, event.excludedRecurrenceRules, event.recurrenceOverrides, event.timeZone ?? null, includeAnchor);
 }
 /**
 * Expand task into occurrences.
 * @param task Task to expand.
 * @param range Date range bounds.
+* @param includeAnchor Whether the source task should be included.
 * @return Generator of expanded occurrences.
 */
-function expandTask(task, range) {
+function expandTask(task, range, includeAnchor) {
 	const anchor = task.start ?? task.due;
 	if (!anchor) return (function* empty() {})();
-	return expandObject(task, range, anchor, task.recurrenceRules, task.excludedRecurrenceRules, task.recurrenceOverrides, task.timeZone ?? null);
+	return expandObject(task, range, anchor, task.recurrenceRules, task.excludedRecurrenceRules, task.recurrenceOverrides, task.timeZone ?? null, includeAnchor);
 }
 /**
 * Build a stable ordering key for an occurrence.
@@ -1381,9 +1387,10 @@ function occurrenceKey(value) {
 * @param excludedRules Exclusion recurrence rules.
 * @param overrides Recurrence overrides keyed by LocalDateTime.
 * @param recurrenceIdTimeZone Optional time zone for recurrence IDs.
+* @param includeAnchor Whether the source item should be included.
 * @return Generator of expanded occurrences.
 */
-function* expandObject(base, range, anchor, rules, excludedRules, overrides, recurrenceIdTimeZone) {
+function* expandObject(base, range, anchor, rules, excludedRules, overrides, recurrenceIdTimeZone, includeAnchor = true) {
 	const hasZone = Boolean(recurrenceIdTimeZone);
 	const fromLocal = hasZone && recurrenceIdTimeZone ? dateTimeInTimeZone(range.from, recurrenceIdTimeZone) : localDateTimeFromDate(range.from);
 	const toLocal = hasZone && recurrenceIdTimeZone ? dateTimeInTimeZone(range.to, recurrenceIdTimeZone) : localDateTimeFromDate(range.to);
@@ -1391,9 +1398,11 @@ function* expandObject(base, range, anchor, rules, excludedRules, overrides, rec
 	const toDate = range.to;
 	const overrideKeys = overrides ? Object.keys(overrides) : [];
 	if (!rules || rules.length === 0) {
-		if (hasZone && recurrenceIdTimeZone) {
-			if (isInRangeWithZone(anchor, fromDate, toDate, recurrenceIdTimeZone)) yield base;
-		} else if (isInRange(anchor, fromLocal, toLocal)) yield base;
+		if (includeAnchor) {
+			if (hasZone && recurrenceIdTimeZone) {
+				if (isInRangeWithZone(anchor, fromDate, toDate, recurrenceIdTimeZone)) yield base;
+			} else if (isInRange(anchor, fromLocal, toLocal)) yield base;
+		}
 		for (const key of overrideKeys) {
 			const instance = buildInstance(base, key, recurrenceIdTimeZone, overrides ? overrides[key] : void 0);
 			if (!instance) continue;
@@ -1413,11 +1422,12 @@ function* expandObject(base, range, anchor, rules, excludedRules, overrides, rec
 		const expanded = expandRule(anchor, rule, fromLocal, toLocal, true, recurrenceIdTimeZone ?? void 0, fromDate, toDate);
 		for (const value of expanded) excluded.add(value);
 	}
-	if (!occurrences.includes(anchor)) occurrences.push(anchor);
+	if (includeAnchor && !occurrences.includes(anchor)) occurrences.push(anchor);
 	for (const key of overrideKeys) if (!occurrences.includes(key)) occurrences.push(key);
 	let sorted = Array.from(new Set(occurrences)).sort((a, b) => compareLocal(a, b, recurrenceIdTimeZone ?? void 0));
 	if (rules[0]?.count && sorted.length > rules[0].count) sorted = sorted.slice(0, rules[0].count);
 	for (const dt of sorted) {
+		if (!includeAnchor && dt === anchor) continue;
 		if (excluded.has(dt)) continue;
 		const instance = buildInstance(base, dt, recurrenceIdTimeZone, overrides ? overrides[dt] : void 0);
 		if (!instance) continue;
@@ -3955,8 +3965,8 @@ const JsCal = {
 	filterByDateRange(items, range, options) {
 		return filterByDateRange(normalizeItems(items), range, options);
 	},
-	expandRecurrence(items, range) {
-		return expandRecurrence(normalizeItems(items), range);
+	expandRecurrence(items, range, options) {
+		return expandRecurrence(normalizeItems(items), range, options);
 	},
 	expandRecurrencePaged(items, range, options) {
 		return expandRecurrencePaged(normalizeItems(items), range, options);

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@craftguild/jscalendar",
-    "version": "0.5.6",
+    "version": "0.6.0",
     "description": "RFC 8984 (JSCalendar) data model helpers for TypeScript",
     "license": "MIT",
     "type": "module",