@apiary-dev/core 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,15 @@
+ISC License
+
+Copyright (c) 2026 IngeniumOfficial
+
+Permission to use, copy, modify, and/or distribute this software for any
+purpose with or without fee is hereby granted, provided that the above
+copyright notice and this permission notice appear in all copies.
+
+THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.

package/README.md

@@ -1,3 +1,60 @@
-# Temporary Holding Version
+# @apiary-dev/core
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Zero-dependency, framework-agnostic scheduling domain logic: slot generation,
+collision and buffer math, timezone-safe weekly rules, and headless calendar
+grids.
+
+- No runtime dependencies; built on `Date` and `Intl`
+- TypeScript-first: bundled ESM/CJS with types on npm
+- Runs on Node.js, Deno, Bun, and Cloudflare Workers
+
+## Install
+
+```bash
+pnpm add @apiary-dev/core
+```
+
+## Example
+
+Carve an operating window into bookable slots:
+
+```ts
+import { generateTimeSlots } from "@apiary-dev/core";
+
+const slots = generateTimeSlots({
+  windows: [
+    {
+      start: new Date("2026-01-05T09:00:00Z"),
+      end: new Date("2026-01-05T17:00:00Z"),
+    },
+  ],
+  existingBookings: [],
+  durationMinutes: 30,
+  intervalMinutes: 15,
+  buffers: { beforeMinutes: 5, afterMinutes: 5 },
+  minNoticeMinutes: 30,
+  maxHorizonMinutes: 7 * 24 * 60,
+});
+```
+
+Expand weekly recurring rules into windows:
+
+```ts
+import { expandWeeklyRules } from "@apiary-dev/core";
+
+const windows = expandWeeklyRules({
+  rules: [{ dayOfWeek: 1, startTime: "09:00", endTime: "17:00" }],
+  startDate: new Date("2026-01-05T00:00:00Z"),
+  endDate: new Date("2026-01-12T00:00:00Z"),
+  timeZone: "America/New_York",
+});
+```
+
+## Documentation
+
+Full API reference and guides are available at
+[apiary-f4n.pages.dev/reference/core/](https://apiary-f4n.pages.dev/reference/core/).
+
+## License
+
+ISC

package/dist/index.cjs

@@ -0,0 +1,437 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  BookingConflictError: () => BookingConflictError,
+  ValidationError: () => ValidationError,
+  applyBufferToRange: () => applyBufferToRange,
+  buildMonthMatrix: () => buildMonthMatrix,
+  buildMultiMonthMatrix: () => buildMultiMonthMatrix,
+  buildMultiWeekMatrix: () => buildMultiWeekMatrix,
+  buildWeekMatrix: () => buildWeekMatrix,
+  expandWeeklyRules: () => expandWeeklyRules,
+  generateTimeSlots: () => generateTimeSlots,
+  rangesOverlap: () => rangesOverlap,
+  utcToWallClock: () => utcToWallClock,
+  wallClockToUTC: () => wallClockToUTC
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var BookingConflictError = class extends Error {
+  constructor(message = "Requested slot overlaps an existing booking or hold") {
+    super(message);
+    this.name = "BookingConflictError";
+  }
+};
+var ValidationError = class extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "ValidationError";
+  }
+};
+
+// src/rules/collisions.ts
+function rangesOverlap(a, b) {
+  return a.start < b.end && a.end > b.start;
+}
+function applyBufferToRange(range, buffer) {
+  const beforeMs = (buffer?.beforeMinutes ?? 0) * 60 * 1e3;
+  const afterMs = (buffer?.afterMinutes ?? 0) * 60 * 1e3;
+  return {
+    start: new Date(range.start.getTime() - beforeMs),
+    end: new Date(range.end.getTime() + afterMs)
+  };
+}
+
+// src/engine/generator.ts
+function generateTimeSlots(options, now = /* @__PURE__ */ new Date()) {
+  const {
+    windows,
+    existingBookings,
+    durationMinutes,
+    intervalMinutes,
+    buffers = {},
+    minNoticeMinutes = 0,
+    maxHorizonMinutes
+  } = options;
+  if (windows.length === 0) return [];
+  const slotDurationMs = durationMinutes * 60 * 1e3;
+  const stepIntervalMs = intervalMinutes * 60 * 1e3;
+  const bufferBeforeMs = (buffers.beforeMinutes ?? 0) * 60 * 1e3;
+  const bufferAfterMs = (buffers.afterMinutes ?? 0) * 60 * 1e3;
+  const minNoticeCutoff = new Date(
+    now.getTime() + minNoticeMinutes * 60 * 1e3
+  );
+  const maxHorizonCutoff = maxHorizonMinutes !== void 0 ? new Date(now.getTime() + maxHorizonMinutes * 60 * 1e3) : null;
+  const bufferedBookings = existingBookings.map(
+    (b) => applyBufferToRange(b, buffers)
+  );
+  const candidateSlots = [];
+  for (const window of windows) {
+    let currentStartMs = window.start.getTime();
+    const windowEndMs = window.end.getTime();
+    while (currentStartMs + slotDurationMs <= windowEndMs) {
+      const slotStart = new Date(currentStartMs);
+      const slotEnd = new Date(currentStartMs + slotDurationMs);
+      const bufferedStartMs = currentStartMs - bufferBeforeMs;
+      const bufferedEndMs = currentStartMs + slotDurationMs + bufferAfterMs;
+      let available = true;
+      let reason = "AVAILABLE";
+      if (slotStart < minNoticeCutoff) {
+        available = false;
+        reason = "MIN_NOTICE_VIOLATION";
+      }
+      if (available && maxHorizonCutoff !== null && slotStart.getTime() > maxHorizonCutoff.getTime()) {
+        available = false;
+        reason = "MAX_HORIZON_EXCEEDED";
+      }
+      if (available && (bufferedStartMs < window.start.getTime() || bufferedEndMs > windowEndMs)) {
+        available = false;
+        reason = "OUTSIDE_BOUNDS";
+      }
+      if (available) {
+        const candidateRange = { start: slotStart, end: slotEnd };
+        const bufferedCandidate = applyBufferToRange(candidateRange, buffers);
+        const hasCollision = bufferedBookings.some(
+          (booking) => rangesOverlap(bufferedCandidate, booking)
+        );
+        if (hasCollision) {
+          available = false;
+          reason = "COLLISION";
+        }
+      }
+      candidateSlots.push({
+        start: slotStart,
+        end: slotEnd,
+        available,
+        reason
+      });
+      currentStartMs += stepIntervalMs;
+    }
+  }
+  return candidateSlots;
+}
+
+// src/engine/calendar.ts
+var toDateKey = (d) => `${d.getFullYear()}-${String(d.getMonth() + 1).padStart(2, "0")}-${String(d.getDate()).padStart(2, "0")}`;
+function buildMonthMatrix(options) {
+  const { year, month, weekStartsOn = 0 } = options;
+  const todayStr = toDateKey(/* @__PURE__ */ new Date());
+  const firstDayOfMonth = new Date(year, month - 1, 1);
+  let startOffset = firstDayOfMonth.getDay() - weekStartsOn;
+  if (startOffset < 0) startOffset += 7;
+  const startDate = new Date(firstDayOfMonth);
+  startDate.setDate(startDate.getDate() - startOffset);
+  const grid = [];
+  const currentDate = new Date(startDate);
+  for (let week = 0; week < 6; week++) {
+    const weekRow = [];
+    for (let day = 0; day < 7; day++) {
+      const isoString = toDateKey(currentDate);
+      const isCurrentMonth = currentDate.getMonth() === month - 1;
+      const dayOfWeek = currentDate.getDay();
+      weekRow.push({
+        date: new Date(currentDate),
+        isoString,
+        dayOfMonth: currentDate.getDate(),
+        dayOfWeek,
+        isCurrentMonth,
+        isToday: isoString === todayStr,
+        isWeekend: dayOfWeek === 0 || dayOfWeek === 6,
+        isBlocked: !isCurrentMonth,
+        blockReason: !isCurrentMonth ? "OUT_OF_BOUNDS" : void 0
+      });
+      currentDate.setDate(currentDate.getDate() + 1);
+    }
+    grid.push(weekRow);
+  }
+  return grid;
+}
+function buildWeekMatrix(options) {
+  const { targetDate, weekStartsOn = 0 } = options;
+  const todayStr = toDateKey(/* @__PURE__ */ new Date());
+  const startOfWeek = new Date(targetDate);
+  let dayOffset = startOfWeek.getDay() - weekStartsOn;
+  if (dayOffset < 0) dayOffset += 7;
+  startOfWeek.setDate(startOfWeek.getDate() - dayOffset);
+  const week = [];
+  const currentDate = new Date(startOfWeek);
+  for (let i = 0; i < 7; i++) {
+    const isoString = toDateKey(currentDate);
+    const dayOfWeek = currentDate.getDay();
+    const isCurrentMonth = currentDate.getFullYear() === targetDate.getFullYear() && currentDate.getMonth() === targetDate.getMonth();
+    week.push({
+      date: new Date(currentDate),
+      isoString,
+      dayOfMonth: currentDate.getDate(),
+      dayOfWeek,
+      isCurrentMonth,
+      isToday: isoString === todayStr,
+      isWeekend: dayOfWeek === 0 || dayOfWeek === 6,
+      isBlocked: !isCurrentMonth,
+      blockReason: !isCurrentMonth ? "OUT_OF_BOUNDS" : void 0
+    });
+    currentDate.setDate(currentDate.getDate() + 1);
+  }
+  return week;
+}
+function buildMultiWeekMatrix(options) {
+  const {
+    startDate,
+    endDate,
+    maxWeeksAllowed = 12,
+    weekStartsOn = 0
+  } = options;
+  const todayStr = toDateKey(/* @__PURE__ */ new Date());
+  const cursor = new Date(startDate);
+  let dayOffset = cursor.getDay() - weekStartsOn;
+  if (dayOffset < 0) dayOffset += 7;
+  cursor.setDate(cursor.getDate() - dayOffset);
+  const weeks = [];
+  let weekCount = 0;
+  const startMs = new Date(
+    startDate.getFullYear(),
+    startDate.getMonth(),
+    startDate.getDate()
+  ).getTime();
+  const endMs = new Date(
+    endDate.getFullYear(),
+    endDate.getMonth(),
+    endDate.getDate()
+  ).getTime();
+  while (cursor.getTime() <= endMs && weekCount < maxWeeksAllowed) {
+    const weekRow = [];
+    for (let i = 0; i < 7; i++) {
+      const currentMs = new Date(
+        cursor.getFullYear(),
+        cursor.getMonth(),
+        cursor.getDate()
+      ).getTime();
+      const isoString = toDateKey(cursor);
+      const dayOfWeek = cursor.getDay();
+      const isOutOfBounds = currentMs < startMs || currentMs > endMs;
+      weekRow.push({
+        date: new Date(cursor),
+        isoString,
+        dayOfMonth: cursor.getDate(),
+        dayOfWeek,
+        isCurrentMonth: true,
+        isToday: isoString === todayStr,
+        isWeekend: dayOfWeek === 0 || dayOfWeek === 6,
+        isBlocked: isOutOfBounds,
+        blockReason: isOutOfBounds ? "OUT_OF_BOUNDS" : void 0
+      });
+      cursor.setDate(cursor.getDate() + 1);
+    }
+    weeks.push(weekRow);
+    weekCount++;
+  }
+  return weeks;
+}
+function buildMultiMonthMatrix(options) {
+  const {
+    startDate,
+    endDate,
+    maxMonthsAllowed = 12,
+    weekStartsOn = 0
+  } = options;
+  const startMs = new Date(
+    startDate.getFullYear(),
+    startDate.getMonth(),
+    startDate.getDate()
+  ).getTime();
+  const endMs = new Date(
+    endDate.getFullYear(),
+    endDate.getMonth(),
+    endDate.getDate()
+  ).getTime();
+  const months = [];
+  let currentYear = startDate.getFullYear();
+  let currentMonth = startDate.getMonth() + 1;
+  let monthCount = 0;
+  const targetEndYear = endDate.getFullYear();
+  const targetEndMonth = endDate.getMonth() + 1;
+  while ((currentYear < targetEndYear || currentYear === targetEndYear && currentMonth <= targetEndMonth) && monthCount < maxMonthsAllowed) {
+    const baseGrid = buildMonthMatrix({
+      year: currentYear,
+      month: currentMonth,
+      weekStartsOn
+    });
+    const scopedGrid = baseGrid.map(
+      (weekRow) => weekRow.map((cell) => {
+        const cellMs = new Date(
+          cell.date.getFullYear(),
+          cell.date.getMonth(),
+          cell.date.getDate()
+        ).getTime();
+        const isOutOfBounds = cellMs < startMs || cellMs > endMs || !cell.isCurrentMonth;
+        return {
+          ...cell,
+          isBlocked: isOutOfBounds,
+          blockReason: isOutOfBounds ? "OUT_OF_BOUNDS" : void 0
+        };
+      })
+    );
+    months.push({
+      year: currentYear,
+      month: currentMonth,
+      grid: scopedGrid
+    });
+    monthCount++;
+    currentMonth++;
+    if (currentMonth > 12) {
+      currentMonth = 1;
+      currentYear++;
+    }
+  }
+  return months;
+}
+
+// src/engine/timezone.ts
+var wallClockToUTC = (wallClock, timeZone) => {
+  const pad = (n) => String(n).padStart(2, "0");
+  const isoStr = `${wallClock.year}-${pad(wallClock.month)}-${pad(wallClock.day)}T${pad(wallClock.hour)}:${pad(wallClock.minute)}:00`;
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  });
+  const utcGuess = /* @__PURE__ */ new Date(`${isoStr}Z`);
+  const parts = Object.fromEntries(
+    formatter.formatToParts(utcGuess).map((p) => [p.type, p.value])
+  );
+  const localHeader = `${parts.year}-${parts.month}-${parts.day}T${parts.hour === "24" ? "00" : parts.hour}:${parts.minute}:${parts.second}`;
+  const diffMs = (/* @__PURE__ */ new Date(`${isoStr}Z`)).getTime() - (/* @__PURE__ */ new Date(`${localHeader}Z`)).getTime();
+  return new Date(utcGuess.getTime() + diffMs);
+};
+var utcToWallClock = (date, timeZone) => {
+  const formatter = new Intl.DateTimeFormat("en-US", {
+    timeZone,
+    year: "numeric",
+    month: "2-digit",
+    day: "2-digit",
+    hour: "2-digit",
+    minute: "2-digit",
+    second: "2-digit",
+    hour12: false
+  });
+  const parts = Object.fromEntries(
+    formatter.formatToParts(date).map((p) => [p.type, p.value])
+  );
+  return {
+    year: Number(parts.year),
+    month: Number(parts.month),
+    day: Number(parts.day),
+    hour: parts.hour === "24" ? 0 : Number(parts.hour),
+    minute: Number(parts.minute)
+  };
+};
+
+// src/engine/weekly.ts
+var DAY_MS = 24 * 60 * 60 * 1e3;
+var parseTime = (time) => {
+  const match = /^(\d{1,2}):(\d{2})$/.exec(time.trim());
+  if (!match) {
+    throw new Error(`Invalid time "${time}" \u2014 expected 24-hour "HH:mm".`);
+  }
+  const hour = Number(match[1]);
+  const minute = Number(match[2]);
+  if (hour > 23 || minute > 59) {
+    throw new Error(`Invalid time "${time}" \u2014 hour/minute out of range.`);
+  }
+  return { hour, minute };
+};
+var weekdayOf = (wallClock) => new Date(wallClock.year, wallClock.month - 1, wallClock.day).getDay();
+function expandWeeklyRules(options) {
+  const { rules, startDate, endDate, timeZone } = options;
+  const startMs = startDate.getTime();
+  const endMs = endDate.getTime();
+  if (endMs <= startMs) return [];
+  const parsedRules = rules.map((rule) => {
+    const start = parseTime(rule.startTime);
+    const end = parseTime(rule.endTime);
+    if (end.hour * 60 + end.minute <= start.hour * 60 + start.minute) {
+      throw new Error(
+        `Rule on day ${rule.dayOfWeek} must have endTime strictly after startTime (overnight spans are not supported).`
+      );
+    }
+    return { dayOfWeek: rule.dayOfWeek, start, end };
+  });
+  const firstUtcDayMs = startMs - startMs % DAY_MS;
+  const lastUtcDayMs = endMs - endMs % DAY_MS + DAY_MS;
+  const windows = [];
+  for (let t = firstUtcDayMs; t <= lastUtcDayMs; t += DAY_MS) {
+    const wallClock = utcToWallClock(new Date(t), timeZone);
+    const weekday = weekdayOf(wallClock);
+    for (const rule of parsedRules) {
+      if (rule.dayOfWeek !== weekday) continue;
+      const windowStart = wallClockToUTC(
+        { ...wallClock, hour: rule.start.hour, minute: rule.start.minute },
+        timeZone
+      );
+      const windowEnd = wallClockToUTC(
+        { ...wallClock, hour: rule.end.hour, minute: rule.end.minute },
+        timeZone
+      );
+      const clippedStart = Math.max(windowStart.getTime(), startMs);
+      const clippedEnd = Math.min(windowEnd.getTime(), endMs);
+      if (clippedEnd > clippedStart) {
+        windows.push({
+          start: new Date(clippedStart),
+          end: new Date(clippedEnd)
+        });
+      }
+    }
+  }
+  windows.sort(
+    (a, b) => a.start.getTime() - b.start.getTime() || a.end.getTime() - b.end.getTime()
+  );
+  const seen = /* @__PURE__ */ new Set();
+  const result = [];
+  for (const window of windows) {
+    const key = `${window.start.getTime()}:${window.end.getTime()}`;
+    if (seen.has(key)) continue;
+    seen.add(key);
+    result.push(window);
+  }
+  return result;
+}
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  BookingConflictError,
+  ValidationError,
+  applyBufferToRange,
+  buildMonthMatrix,
+  buildMultiMonthMatrix,
+  buildMultiWeekMatrix,
+  buildWeekMatrix,
+  expandWeeklyRules,
+  generateTimeSlots,
+  rangesOverlap,
+  utcToWallClock,
+  wallClockToUTC
+});