calendaryjs 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 calendaryjs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,187 @@
+# calendaryjs
+
+A lightweight, plugin-based calendar system for managing events in TypeScript. Inspired by [Day.js](https://github.com/iamkun/dayjs).
+
+## Features
+
+- **🪶 Lightweight** - ~5KB core, tree-shakeable
+- **🔌 Plugin System** - Day.js-style `extend()` API
+- **📅 Many Event Types** - const, fixed, monthly, weekly, nth-weekday, formula, relative (+ plugin types)
+- **🔍 Fluent Query API** - Chain methods for filtering
+- **💾 Caching** - Memoized event generation
+
+## Installation
+
+```bash
+pnpm add calendaryjs
+```
+
+## Quick Start
+
+### Factory API (Recommended)
+
+Author events with the **builder** — it reads like a sentence and compiles to the
+plain config shown under [Collections](#collections):
+
+```typescript
+import { calendary } from "calendaryjs";
+import { every, date } from "calendaryjs/builder";
+
+const cal = calendary();
+
+cal.addGroup({
+  id: "holidays",
+  name: "Holidays",
+  events: [
+    every("year").on(date(1, 1)).title("New Year"),
+    every("year").on(date(12, 25)).title("Christmas"),
+  ],
+});
+
+// Read events
+cal.getEvents("2026-12-25");
+cal.getEventsInRange("2026-01-01", "2026-12-31");
+
+// Fluent query
+cal.search().group("holidays").range("2026-01-01", "2026-12-31").getEvents();
+```
+
+> Full grammar (`every`/`from`/`once`, positions, bounds, plugin selectors): the
+> [builder guide](https://calendaryjs.dev/guides/builder/). Hand-writing the plain
+> config also works — both compile to the same model.
+
+### Collections
+
+Bundle events into a portable **collection** (a `.cdy` file is its JSON form) and
+load it with `cal.load()`. It declares the plugins its events need; register those
+first — `load()` validates them and errors clearly if any is missing.
+
+```typescript
+import { calendary } from "calendaryjs";
+import { lunar } from "calendaryjs-plugin-lunar";
+
+const cal = calendary().use(lunar());
+
+cal.load({
+  collection: "holidays",
+  plugins: ["calendaryjs-plugin-lunar"],
+  events: [
+    { type: "const", id: "new-year", month: 1, day: 1, title: "New Year" },
+    { type: "lunar", id: "lunar-new-year", lunarMonth: 1, lunarDay: 1, title: "Lunar New Year" },
+  ],
+});
+
+// …or from a .cdy (JSON) string, e.g. read from disk or fetched
+cal.load(jsonString);
+```
+
+### Class-based API
+
+> `Calendary` is an alias of the canonical `CalendaryInstance` class, kept for Day.js-style familiarity.
+
+```typescript
+import { Calendary } from "calendaryjs";
+
+const cal = new Calendary();
+
+cal.addGroup({
+  id: "holidays",
+  name: "Holidays",
+  events: [
+    { type: "const", id: "newyear", month: 1, day: 1, title: "New Year" },
+    { type: "fixed", id: "wedding", year: 2025, month: 6, day: 15, title: "Wedding" },
+  ],
+});
+```
+
+## Event Types
+
+| Type          | Description                                | Example                      |
+| ------------- | ------------------------------------------ | ---------------------------- |
+| `const`       | Fixed annual date                          | Christmas (Dec 25)           |
+| `fixed`       | One-time date                              | Wedding (Jun 15, 2025)       |
+| `monthly`     | Same day every month (interval/exclusions) | Payday (15th)                |
+| `weekly`      | Same weekday every week (interval/range)   | Standup (Mon)                |
+| `nth-weekday` | Nth weekday of a month, or anchored        | Thanksgiving (4th Thu / Nov) |
+| `formula`     | Custom formula                             | Last Monday of May           |
+| `relative`    | Offset from a registered anchor            | 49 days after an anchor      |
+
+Plugins add more types (e.g. `lunar`, `hijri`, `liturgical`).
+
+## Plugin System
+
+```typescript
+import { calendary } from "calendaryjs";
+
+// Extend with custom functionality
+calendary.extend((option, C, d) => {
+  C.prototype.myMethod = function () {
+    return "custom method";
+  };
+});
+
+// Use plugins
+import { lunar } from "calendaryjs-plugin-lunar";
+
+const cal = calendary();
+cal.use(lunar());
+```
+
+## Event Properties
+
+Every event shares `BaseEventProperties` (below) plus its type-specific date fields.
+**`id`, `type`, and `title` are required; everything else is optional.**
+
+### Identity & display
+
+| Property      | Type     | Notes                                                                                                   |
+| ------------- | -------- | ------------------------------------------------------------------------------------------------------- |
+| `id`          | `string` | unique id — _required_                                                                                  |
+| `type`        | `string` | `const` · `fixed` · `monthly` · `weekly` · `nth-weekday` · `formula` · `relative` · plugin — _required_ |
+| `title`       | `string` | _required_                                                                                              |
+| `description` | `string` | —                                                                                                       |
+| `location`    | `string` | —                                                                                                       |
+| `url`         | `string` | —                                                                                                       |
+| `icon`        | `string` | emoji or glyph                                                                                          |
+| `color`       | `string` | —                                                                                                       |
+
+### Timing
+
+| Property    | Type      | Notes     |
+| ----------- | --------- | --------- |
+| `allDay`    | `boolean` | —         |
+| `startTime` | `string`  | `"09:00"` |
+| `endTime`   | `string`  | `"17:00"` |
+| `duration`  | `number`  | —         |
+
+### Classification
+
+| Property     | Type                                        | Notes                                                |
+| ------------ | ------------------------------------------- | ---------------------------------------------------- |
+| `keywords`   | `string[]`                                  | —                                                    |
+| `categories` | `string[]`                                  | —                                                    |
+| `status`     | `'confirmed' \| 'tentative' \| 'cancelled'` | —                                                    |
+| `priority`   | `number`                                    | z-index on a shared day; higher = on top (default 0) |
+| `source`     | `string`                                    | origin: plugin / feed / ICS subscription             |
+| `metadata`   | `Record<string, unknown>`                   | arbitrary per-event data                             |
+| `reminders`  | `Reminder[]`                                | —                                                    |
+
+### Recurrence control
+
+| Property        | Type               | Notes                                                           |
+| --------------- | ------------------ | --------------------------------------------------------------- |
+| `onConflict`    | `ConflictResolver` | same-day conflict: keep / drop / reschedule                     |
+| `overrideDates` | `OverrideDatesMap` | force-move an occurrence to another date                        |
+| `exceptions`    | `EventExceptions`  | per-occurrence skip / override (ICS `EXDATE` / `RECURRENCE-ID`) |
+
+## Plugins
+
+| Package                                                                                                   | Description            |
+| --------------------------------------------------------------------------------------------------------- | ---------------------- |
+| [calendaryjs-plugin-lunar](https://github.com/calendaryjs/calendaryjs/tree/main/packages/lunar)           | Lunar calendar events  |
+| [calendaryjs-plugin-liturgical](https://github.com/calendaryjs/calendaryjs/tree/main/packages/liturgical) | Easter & offset events |
+| [calendaryjs-plugin-hijri](https://github.com/calendaryjs/calendaryjs/tree/main/packages/hijri)           | Islamic (Hijri) events |
+
+## License
+
+MIT