workclock 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Karthik P
+
+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/NOTICE

@@ -0,0 +1,28 @@
+workclock
+Copyright (c) 2026 Karthik P
+
+Parts of the test suite are ported from businesstimedelta
+(https://github.com/seppemans/businesstimedelta), which is distributed
+under the following license:
+
+The MIT License (MIT)
+
+Copyright (c) 2015 Sebastiaan Boer
+
+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

@@ -1,3 +1,85 @@
-# Temporary Holding Version
+# workclock
 
-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.
+Business-time arithmetic for JavaScript and TypeScript: working hours, breaks,
+holidays and IANA time zones, compiled from Rust to WebAssembly.
+
+## Install
+
+```sh
+npm install workclock
+```
+
+It runs on Node.js 22 or later, in bundlers and in browsers, and ships its
+TypeScript types.
+
+## Quickstart
+
+A London support desk works 09:00–17:00 with a lunch break, and is closed on
+Christmas Day and the substitute Boxing Day holiday. A ticket opened at 16:30
+on Christmas Eve with an 8-hour SLA:
+
+```js
+import { Schedule } from "workclock";
+
+const support = new Schedule({
+  timeZone: "Europe/London",
+  rules: [
+    { type: "workday", start: "09:00", end: "17:00" },
+    { type: "break", start: "12:00", end: "13:00" },
+    { type: "holidays", dates: ["2026-12-25", "2026-12-28"] },
+  ],
+});
+
+support.add("2026-12-24T16:30:00Z", 8 * 3_600_000); // Date 2026-12-30T09:30:00.000Z
+support.between("2026-12-24T16:30:00Z", new Date("2026-12-29T11:00:00Z")); // 9000000 ms
+support.nextPeriod("2026-12-29T11:00:00Z").end; // Date 2026-12-29T12:00:00.000Z
+```
+
+`sub` counts back, and `previousPeriod` finds the period of working time at or
+before an instant. Rules are `"workday"`, `"break"` or `"holidays"`; times are
+`HH:MM[:SS[.fff]]`, `days` defaults to Monday to Friday, and each rule can set
+its own `timeZone`.
+
+## Instants and durations
+
+- Instants are `Date`s or ISO 8601 strings with a UTC offset, such as
+  `"2026-01-05T09:00:00Z"` or `"2026-01-05T10:00:00+01:00"`. A string without
+  an offset is rejected.
+- Durations are whole numbers of milliseconds, negative to go back in time.
+  Any other type throws `TypeError`; it is not converted.
+- Results are `Date`s and numbers, exact to the millisecond.
+- The supported range is -009999-01-02T01:59:59Z to 9999-12-30T22:00:00Z.
+
+`betweenMany`, `addMany` and `subMany` take arrays of instants, or a
+`Float64Array` of epoch milliseconds for the fastest path, and process them in
+one call.
+
+## Errors
+
+Schedule errors are instances of `WorkclockError`, with a `kind`:
+
+| Class | `kind` | Thrown when |
+|---|---|---|
+| `NoWorkingTimeError` | `"no_working_time"` | The rules have no working time, or a search finds none within 366 days, plus seven days per holiday date. |
+| `OutOfRangeError` | `"out_of_range"` | An instant or a result is outside the supported range. |
+| `UnknownZoneError` | `"unknown_zone"` | A time zone is not in the IANA database. |
+
+`WorkclockError` itself has the kind `"unknown"`. Malformed input, such as a
+rule without `start` or a string without an offset, throws a built-in
+`TypeError` or `RangeError` instead.
+
+## Browsers without a bundler
+
+Import from `workclock/web`, and call its default export once before using
+anything else: `await init()` fetches `workclock_bg.wasm` from the package's
+`pkg/web/` directory, so serve that directory with your page. With a bundler,
+or in Node.js, import from `workclock` as above.
+
+## Links
+
+- [Repository](https://github.com/Karthik-beta/workclock)
+- [Specification and examples](https://github.com/Karthik-beta/workclock/blob/main/DESIGN.md)
+- [JavaScript examples](https://github.com/Karthik-beta/workclock/tree/main/js/examples)
+- [Changelog](https://github.com/Karthik-beta/workclock/blob/main/CHANGELOG.md)
+
+MIT licensed.

package/bundler.d.ts

@@ -0,0 +1,2 @@
+export * from "./pkg/bundler/workclock.js";
+export * from "./errors.js";

package/bundler.js

@@ -0,0 +1,2 @@
+export * from "./pkg/bundler/workclock.js";
+export * from "./errors.js";

package/errors.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Base class of the errors a schedule throws; check with `instanceof`.
+ *
+ * Malformed input, such as a rule without `start` or an instant string
+ * without a UTC offset, throws a built-in `TypeError` or `RangeError`
+ * instead, which is not a `WorkclockError`.
+ */
+export declare class WorkclockError extends Error {
+  /**
+   * `"no_working_time"`, `"out_of_range"` or `"unknown_zone"` for the
+   * subclasses below, or `"unknown"` for an error this version does not
+   * classify further.
+   */
+  readonly kind: string;
+}
+
+/**
+ * The rules have no working time, or a search found none within 366 days,
+ * plus seven days per holiday date.
+ */
+export declare class NoWorkingTimeError extends WorkclockError {
+  readonly kind: "no_working_time";
+}
+
+/**
+ * An instant falls outside the supported range, -009999-01-02T01:59:59Z to
+ * 9999-12-30T22:00:00Z.
+ */
+export declare class OutOfRangeError extends WorkclockError {
+  readonly kind: "out_of_range";
+}
+
+/** A time zone name is not in the IANA database. */
+export declare class UnknownZoneError extends WorkclockError {
+  readonly kind: "unknown_zone";
+}

package/errors.js

@@ -0,0 +1,46 @@
+// The WebAssembly module throws plain `Error` objects carrying a `kind`, so
+// besides the usual prototype check these classes recognise errors by `kind`.
+// That also keeps `instanceof` working across the node, bundler and web builds.
+
+function isInstance(Class, value, kinds) {
+  return (
+    Function.prototype[Symbol.hasInstance].call(Class, value) ||
+    (value instanceof Error && kinds.includes(value.kind))
+  );
+}
+
+export class WorkclockError extends Error {
+  name = "WorkclockError";
+  kind = "unknown";
+
+  static [Symbol.hasInstance](value) {
+    return isInstance(this, value, ["no_working_time", "out_of_range", "unknown_zone", "unknown"]);
+  }
+}
+
+export class NoWorkingTimeError extends WorkclockError {
+  name = "NoWorkingTimeError";
+  kind = "no_working_time";
+
+  static [Symbol.hasInstance](value) {
+    return isInstance(this, value, ["no_working_time"]);
+  }
+}
+
+export class OutOfRangeError extends WorkclockError {
+  name = "OutOfRangeError";
+  kind = "out_of_range";
+
+  static [Symbol.hasInstance](value) {
+    return isInstance(this, value, ["out_of_range"]);
+  }
+}
+
+export class UnknownZoneError extends WorkclockError {
+  name = "UnknownZoneError";
+  kind = "unknown_zone";
+
+  static [Symbol.hasInstance](value) {
+    return isInstance(this, value, ["unknown_zone"]);
+  }
+}

package/node.d.ts

@@ -0,0 +1,2 @@
+export * from "./pkg/node/workclock.js";
+export * from "./errors.js";

package/node.js

@@ -0,0 +1,2 @@
+export * from "./pkg/node/workclock.js";
+export * from "./errors.js";

package/package.json

@@ -1,6 +1,88 @@
 {
   "name": "workclock",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "Fast, correct business-time arithmetic: working hours, SLAs and shifts",
+  "keywords": [
+    "business-hours",
+    "working-hours",
+    "sla",
+    "timezone",
+    "shift",
+    "business-time"
+  ],
+  "license": "MIT",
+  "author": "Karthik P",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Karthik-beta/workclock.git",
+    "directory": "js"
+  },
+  "homepage": "https://github.com/Karthik-beta/workclock#readme",
+  "bugs": "https://github.com/Karthik-beta/workclock/issues",
+  "type": "module",
+  "exports": {
+    ".": {
+      "node": {
+        "types": "./node.d.ts",
+        "default": "./node.js"
+      },
+      "browser": {
+        "types": "./bundler.d.ts",
+        "default": "./bundler.js"
+      },
+      "default": {
+        "types": "./bundler.d.ts",
+        "default": "./bundler.js"
+      }
+    },
+    "./web": {
+      "types": "./web.d.ts",
+      "default": "./web.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "types": "./node.d.ts",
+  "files": [
+    "node.js",
+    "node.d.ts",
+    "bundler.js",
+    "bundler.d.ts",
+    "web.js",
+    "web.d.ts",
+    "errors.js",
+    "errors.d.ts",
+    "pkg/*/package.json",
+    "pkg/*/workclock.js",
+    "pkg/*/workclock.d.ts",
+    "pkg/*/workclock_bg.js",
+    "pkg/*/workclock_bg.wasm",
+    "pkg/*/workclock_bg.wasm.d.ts",
+    "README.md",
+    "LICENSE",
+    "NOTICE"
+  ],
+  "sideEffects": [
+    "./pkg/bundler/workclock.js"
+  ],
+  "engines": {
+    "node": ">=22"
+  },
+  "scripts": {
+    "build": "npm run build:node && npm run build:bundler && npm run build:web && npm run build:unignore",
+    "build:node": "wasm-pack build ../crates/workclock-wasm --release --target nodejs --out-dir ../../js/pkg/node --out-name workclock",
+    "build:bundler": "wasm-pack build ../crates/workclock-wasm --release --target bundler --out-dir ../../js/pkg/bundler --out-name workclock",
+    "build:web": "wasm-pack build ../crates/workclock-wasm --release --target web --out-dir ../../js/pkg/web --out-name workclock",
+    "build:unignore": "node --eval \"for (const t of ['node', 'bundler', 'web']) require('node:fs').rmSync('pkg/' + t + '/.gitignore', { force: true })\"",
+    "prepack": "node --eval \"for (const f of ['LICENSE', 'NOTICE']) require('node:fs').copyFileSync('../' + f, f)\"",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "bench": "node bench/bench.js"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.5",
+    "fast-check": "^4.10.2",
+    "tinybench": "^6.2.2",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.5"
+  }
+}

package/pkg/bundler/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "workclock-wasm",
+  "type": "module",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/Karthik-beta/workclock"
+  },
+  "files": [
+    "workclock_bg.wasm",
+    "workclock.js",
+    "workclock_bg.js",
+    "workclock.d.ts"
+  ],
+  "main": "workclock.js",
+  "types": "workclock.d.ts",
+  "sideEffects": [
+    "./workclock.js",
+    "./snippets/*"
+  ]
+}

package/pkg/bundler/workclock.d.ts

@@ -0,0 +1,209 @@
+/* tslint:disable */
+/* eslint-disable */
+
+/** A day of the week. */
+export type Weekday = "mon" | "tue" | "wed" | "thu" | "fri" | "sat" | "sun";
+
+/**
+ * Working hours (`"workday"`) or time off within them (`"break"`) on some days
+ * of the week. Times are wall-clock times in the rule's time zone, written
+ * `HH:MM`, `HH:MM:SS` or `HH:MM:SS.fff` on a 24-hour clock, such as `"09:00"`
+ * or `"17:30:00"`.
+ */
+export interface HoursRule {
+    type: "workday" | "break";
+    /** Wall-clock start, such as `"09:00"`. */
+    start: string;
+    /** Wall-clock end; at or before `start` means the hours end the next day. */
+    end: string;
+    /**
+     * Days on which the hours start. Defaults to Monday to Friday, for breaks
+     * too, so a break on a weekend workday needs its own `days`.
+     */
+    days?: readonly Weekday[];
+    /** IANA time zone; defaults to the schedule's. */
+    timeZone?: string;
+}
+
+/** Dates that are not worked, each from 00:00 to the next 00:00. */
+export interface HolidaysRule {
+    type: "holidays";
+    /** Dates such as `"2026-12-25"`. */
+    dates: readonly string[];
+    /** IANA time zone; defaults to the schedule's. */
+    timeZone?: string;
+}
+
+/**
+ * One rule of a schedule. Working time is the time inside workdays and
+ * outside breaks and holidays.
+ */
+export type Rule = HoursRule | HolidaysRule;
+
+/** What `new Schedule` takes. */
+export interface ScheduleOptions {
+    /** IANA time zone for rules without their own; defaults to `"UTC"`. */
+    timeZone?: string;
+    /** The rules, in any order. */
+    rules: readonly Rule[];
+}
+
+/** A `Date`, or an ISO 8601 string with a UTC offset. */
+export type Instant = Date | string;
+
+/** A period: a maximal stretch of working time. */
+export interface Period {
+    start: Date;
+    end: Date;
+}
+
+/**
+ * Batch methods. Instants come as an array of `Instant`s, returning numbers or
+ * `Date`s, or as a `Float64Array` of milliseconds since the epoch, returning a
+ * `Float64Array`. Durations come as one number for every item, or one per item.
+ * A failing item throws, naming its index.
+ */
+export interface Schedule {
+    /**
+     * `between` for each pair.
+     * @throws {RangeError} If `a` and `b` differ in length.
+     */
+    betweenMany(a: Float64Array, b: Float64Array): Float64Array;
+    betweenMany(a: readonly Instant[], b: readonly Instant[]): number[];
+    betweenMany(a: Float64Array | readonly Instant[], b: Float64Array | readonly Instant[]): Float64Array | number[];
+    /** `add` for each instant. */
+    addMany(t: Float64Array, ms: number | readonly number[] | Float64Array): Float64Array;
+    addMany(t: readonly Instant[], ms: number | readonly number[] | Float64Array): Date[];
+    addMany(t: Float64Array | readonly Instant[], ms: number | readonly number[] | Float64Array): Float64Array | Date[];
+    /** `sub` for each instant. */
+    subMany(t: Float64Array, ms: number | readonly number[] | Float64Array): Float64Array;
+    subMany(t: readonly Instant[], ms: number | readonly number[] | Float64Array): Date[];
+    subMany(t: Float64Array | readonly Instant[], ms: number | readonly number[] | Float64Array): Float64Array | Date[];
+}
+
+
+
+/**
+ * Working time defined by rules, evaluated in IANA time zones.
+ *
+ * Instants are `Date`s or ISO 8601 strings with a UTC offset, and durations
+ * are numbers of milliseconds. Results are exact to the millisecond.
+ */
+export class Schedule {
+    free(): void;
+    [Symbol.dispose](): void;
+    /**
+     * Finds the instant a given amount of working time after another.
+     *
+     * @param t The instant to count from.
+     * @param ms Working time in milliseconds; a negative amount counts back.
+     * @returns The earliest instant with `ms` of working time after `t`, or
+     * `t` itself when `ms` is zero.
+     * @throws {NoWorkingTimeError} If no working time is found within 366
+     * days, plus seven days per holiday date.
+     * @throws {OutOfRangeError} If `t` or the result is outside the supported
+     * range.
+     * @throws {TypeError} If `t` is neither a `Date` nor a string, or `ms` is
+     * not a number.
+     * @throws {RangeError} If `t` is malformed, or `ms` is not a whole number
+     * within ±`Number.MAX_SAFE_INTEGER`.
+     * @example
+     * ```js
+     * const due = support.add("2026-12-24T16:30:00Z", 8 * 3_600_000);
+     * due.toISOString(); // "2026-12-30T09:30:00.000Z"
+     * ```
+     */
+    add(t: Instant, ms: number): Date;
+    /**
+     * Measures the working time between two instants.
+     *
+     * @param a The start.
+     * @param b The end.
+     * @returns The working time in milliseconds; negative when `b` is before
+     * `a`.
+     * @throws {OutOfRangeError} If an instant is outside the supported range.
+     * @throws {TypeError} If an instant is neither a `Date` nor a string.
+     * @throws {RangeError} If an instant is an invalid `Date` or a string
+     * without a UTC offset.
+     * @example
+     * ```js
+     * support.between("2026-01-05T09:00:00Z", "2026-01-06T09:00:00Z"); // 25200000, 7 hours
+     * ```
+     */
+    between(a: Instant, b: Instant): number;
+    /**
+     * Builds a schedule from its rules.
+     *
+     * @param options The default time zone and the rules.
+     * @throws {UnknownZoneError} If a time zone is not in the IANA database.
+     * @throws {NoWorkingTimeError} If the working hours minus the breaks are
+     * empty.
+     * @throws {TypeError} If `options` or a rule has the wrong shape; the
+     * message names the rule, such as `rules[1]`.
+     * @throws {RangeError} If a time, day or date cannot be read.
+     * @example
+     * ```js
+     * const support = new Schedule({
+     *   timeZone: "Europe/London",
+     *   rules: [
+     *     { type: "workday", start: "09:00", end: "17:00" },
+     *     { type: "break", start: "12:00", end: "13:00" },
+     *     { type: "holidays", dates: ["2026-12-25", "2026-12-28"] },
+     *   ],
+     * });
+     * ```
+     */
+    constructor(options: ScheduleOptions);
+    /**
+     * Finds the period of working time at or after an instant.
+     *
+     * @param t The instant to search from.
+     * @returns The period that contains `t`, starting at `t`, or else the
+     * first one after it.
+     * @throws {NoWorkingTimeError} If no working time is found within 366
+     * days, plus seven days per holiday date.
+     * @throws {OutOfRangeError} If `t` is outside the supported range, or the
+     * search reaches its end.
+     * @throws {TypeError} If `t` is neither a `Date` nor a string.
+     * @throws {RangeError} If `t` is malformed.
+     */
+    nextPeriod(t: Instant): Period;
+    /**
+     * Finds the period of working time at or before an instant.
+     *
+     * @param t The instant to search back from.
+     * @returns The period that contains `t`, ending at `t`, or else the last
+     * one before it.
+     * @throws {NoWorkingTimeError} If no working time is found within 366
+     * days, plus seven days per holiday date.
+     * @throws {OutOfRangeError} If `t` is outside the supported range, or the
+     * search reaches its start.
+     * @throws {TypeError} If `t` is neither a `Date` nor a string.
+     * @throws {RangeError} If `t` is malformed.
+     */
+    previousPeriod(t: Instant): Period;
+    /**
+     * Finds the instant a given amount of working time before another.
+     *
+     * @param t The instant to count back from.
+     * @param ms Working time in milliseconds; a negative amount counts
+     * forward.
+     * @returns The latest instant with `ms` of working time before `t`, or
+     * `t` itself when `ms` is zero.
+     * @throws {NoWorkingTimeError} If no working time is found within 366
+     * days, plus seven days per holiday date.
+     * @throws {OutOfRangeError} If `t` or the result is outside the supported
+     * range.
+     * @throws {TypeError} If `t` is neither a `Date` nor a string, or `ms` is
+     * not a number.
+     * @throws {RangeError} If `t` is malformed, or `ms` is not a whole number
+     * within ±`Number.MAX_SAFE_INTEGER`.
+     */
+    sub(t: Instant, ms: number): Date;
+}
+
+/**
+ * Returns the version of workclock this module was built from, such as
+ * `"0.1.0"`.
+ */
+export function version(): string;

package/pkg/bundler/workclock.js

@@ -0,0 +1,9 @@
+/* @ts-self-types="./workclock.d.ts" */
+import * as wasm from "./workclock_bg.wasm";
+import { __wbg_set_wasm } from "./workclock_bg.js";
+
+__wbg_set_wasm(wasm);
+wasm.__wbindgen_start();
+export {
+    Schedule, version
+} from "./workclock_bg.js";