@elaraai/east-web-std 1.0.85

package/dist/src/time.js

@@ -0,0 +1,300 @@
+/**
+ * Copyright (c) 2025 Elara AI Pty Ltd
+ * Dual-licensed under AGPL-3.0 and commercial license. See LICENSE for details.
+ */
+import { East, IntegerType, NullType, DateTimeType, StringType } from "@elaraai/east";
+import { EastError } from "@elaraai/east/internal";
+/**
+ * Computes the UTC offset in minutes for an IANA timezone at a given instant.
+ *
+ * Uses Intl.DateTimeFormat to format the datetime in both UTC and the target
+ * timezone, then computes the difference. It only depends on the date
+ * component formatting, not abbreviations, so it gives east-node-std's answer
+ * wherever `Intl` carries the IANA zones, as every current browser does.
+ */
+function computeUtcOffsetMinutes(datetime, zone) {
+    const formatParts = (tz) => {
+        const fmt = new Intl.DateTimeFormat("en-US", {
+            timeZone: tz,
+            year: "numeric",
+            month: "2-digit",
+            day: "2-digit",
+            hour: "2-digit",
+            minute: "2-digit",
+            second: "2-digit",
+            hour12: false,
+        });
+        const parts = fmt.formatToParts(datetime);
+        const get = (type) => parseInt(parts.find(p => p.type === type).value);
+        return { year: get("year"), month: get("month"), day: get("day"), hour: get("hour"), minute: get("minute"), second: get("second") };
+    };
+    const utc = formatParts("UTC");
+    const local = formatParts(zone);
+    const utcMs = Date.UTC(utc.year, utc.month - 1, utc.day, utc.hour, utc.minute, utc.second);
+    const localMs = Date.UTC(local.year, local.month - 1, local.day, local.hour, local.minute, local.second);
+    return (localMs - utcMs) / 60000;
+}
+/**
+ * Gets the current Unix timestamp in milliseconds.
+ *
+ * Returns the number of milliseconds elapsed since the Unix epoch
+ * (January 1, 1970 00:00:00 UTC). This is useful for timestamping events,
+ * measuring durations, and working with date/time data.
+ *
+ * This is a platform function for the East language, enabling time access
+ * in East programs running in a browser.
+ *
+ * @returns The current time as milliseconds since epoch (January 1, 1970 UTC)
+ *
+ * @example
+ * ```ts
+ * const getTimestamp = East.function([], IntegerType, $ => {
+ *     return Time.now();
+ *     // Returns: 1735689600000n (example)
+ * });
+ * ```
+ */
+export const time_now = East.platform("time_now", [], IntegerType);
+/**
+ * Sleeps for the specified number of milliseconds.
+ *
+ * Pauses execution asynchronously for the given duration. This is a non-blocking
+ * sleep that allows other operations to run during the wait period. Useful for
+ * rate limiting, delays, and timing control.
+ *
+ * This is a platform function for the East language, enabling timed delays
+ * in East programs running in a browser.
+ *
+ * @param ms - The number of milliseconds to sleep (must be non-negative)
+ * @returns Null after sleeping completes
+ *
+ * @throws {EastError} When sleep fails
+ *
+ * @example
+ * ```ts
+ * const delayedTask = East.function([], NullType, $ => {
+ *     $(Console.log("Starting..."));
+ *     $(Time.sleep(1000n));  // Wait 1 second
+ *     $(Console.log("Done!"));
+ * });
+ * ```
+ *
+ * @remarks
+ * A browser may slow the timers of a page in a background tab, so a sleep
+ * there can last longer than asked.
+ */
+export const time_sleep = East.asyncPlatform("time_sleep", [IntegerType], NullType);
+/**
+ * Gets the UTC offset in minutes for an IANA timezone at a given UTC datetime.
+ *
+ * Returns the number of minutes that the given timezone is ahead of (positive)
+ * or behind (negative) UTC at the specified instant. This accounts for DST
+ * transitions — the same timezone can return different offsets depending on
+ * the datetime.
+ *
+ * The timezone must be a valid IANA timezone name (e.g., "Australia/Sydney",
+ * "America/New_York", "Europe/London", "Asia/Tokyo"). See the IANA Time Zone
+ * Database for the full list of valid names.
+ *
+ * @param datetime - A UTC datetime to compute the offset for
+ * @param zone - An IANA timezone name (e.g., "Australia/Sydney")
+ * @returns UTC offset in minutes (e.g., 660 for Sydney in summer, 600 in winter)
+ *
+ * @throws {EastError} When the timezone name is not a valid IANA timezone
+ *
+ * @example
+ * ```ts
+ * const toSydneyTime = East.function([DateTimeType], DateTimeType, ($, dt) => {
+ *     const offset = $.let(Time.getTimezoneOffset(dt, "Australia/Sydney"));
+ *     $.return(dt.addMinutes(offset));
+ * });
+ * ```
+ */
+export const time_get_timezone_offset = East.platform("time_get_timezone_offset", [DateTimeType, StringType], IntegerType);
+/** What a sleep a host stopped fails with. */
+const STOPPED = "the program was stopped";
+/**
+ * Waits a number of milliseconds, unless a signal stops the wait first: then
+ * its timer is cleared, and it fails.
+ */
+function sleepFor(ms, signal) {
+    return new Promise((resolve, reject) => {
+        if (signal?.aborted === true) {
+            reject(new Error(STOPPED));
+            return;
+        }
+        let timer;
+        const stop = () => {
+            clearTimeout(timer);
+            reject(new Error(STOPPED));
+        };
+        timer = setTimeout(() => {
+            signal?.removeEventListener("abort", stop);
+            resolve();
+        }, ms);
+        signal?.addEventListener("abort", stop, { once: true });
+    });
+}
+/**
+ * Browser implementation of time platform functions, whose sleeps a host may
+ * stop.
+ *
+ * @param signal - Stops the program's sleeps, for a host that stops a program
+ *   without ending its thread: once it aborts, a sleep under way fails at
+ *   once, its timer cleared, and a later one fails as it starts. Unset, a
+ *   sleep ends once its time has passed
+ * @returns The platform functions, to pass to {@link East.compileAsync}
+ *
+ * @example
+ * ```ts
+ * const stop = new AbortController();
+ * const compiled = await East.compileAsync(delayedTask.toIR(), createTimeImpl(stop.signal));
+ * const running = compiled();
+ * stop.abort();  // the sleep under way fails at once: "Failed to sleep: the program was stopped"
+ * ```
+ */
+export function createTimeImpl(signal) {
+    return [
+        time_now.implement(() => {
+            try {
+                return BigInt(Date.now());
+            }
+            catch (err) {
+                throw new EastError(`Failed to get current time: ${err.message}`, {
+                    location: [{ filename: "time_now", line: 0n, column: 0n }],
+                    cause: err
+                });
+            }
+        }),
+        time_sleep.implement(async (ms) => {
+            try {
+                await sleepFor(Number(ms), signal);
+            }
+            catch (err) {
+                throw new EastError(`Failed to sleep: ${err.message}`, {
+                    location: [{ filename: "time_sleep", line: 0n, column: 0n }],
+                    cause: err
+                });
+            }
+        }),
+        time_get_timezone_offset.implement((datetime, zone) => {
+            try {
+                const offset = computeUtcOffsetMinutes(datetime, zone);
+                return BigInt(offset);
+            }
+            catch (err) {
+                if (err instanceof RangeError) {
+                    throw new EastError(`Invalid IANA timezone: "${zone}". ` +
+                        `Use a valid IANA timezone name such as "Australia/Sydney", "America/New_York", or "Europe/London". ` +
+                        `See https://en.wikipedia.org/wiki/List_of_tz_database_time_zones for the full list.`, { location: [{ filename: "time_get_timezone_offset", line: 0n, column: 0n }], cause: err });
+                }
+                if (err instanceof EastError)
+                    throw err;
+                throw new EastError(`Failed to get timezone offset for "${zone}": ${err.message}`, {
+                    location: [{ filename: "time_get_timezone_offset", line: 0n, column: 0n }],
+                    cause: err
+                });
+            }
+        }),
+    ];
+}
+/**
+ * Browser implementation of time platform functions.
+ *
+ * Pass this array to {@link East.compileAsync} to enable time operations.
+ */
+const TimeImpl = createTimeImpl();
+/**
+ * Grouped time platform functions.
+ *
+ * Provides time, sleep, and timezone operations for East programs.
+ *
+ * @example
+ * ```ts
+ * import { East, NullType } from "@elaraai/east";
+ * import { Time } from "@elaraai/east-web-std";
+ *
+ * const timedTask = East.function([], NullType, $ => {
+ *     const start = $.let(Time.now());
+ *     $(Time.sleep(1000n)); // Sleep for 1 second
+ *     const end = $.let(Time.now());
+ * });
+ *
+ * const compiled = await East.compileAsync(timedTask.toIR(), Time.Implementation);
+ * await compiled();
+ * ```
+ */
+export const Time = {
+    /**
+     * Gets the current Unix timestamp in milliseconds.
+     *
+     * Returns the number of milliseconds elapsed since the Unix epoch
+     * (January 1, 1970 00:00:00 UTC). Useful for timestamping and measuring durations.
+     *
+     * @returns The current time as milliseconds since epoch
+     *
+     * @example
+     * ```ts
+     * const getTimestamp = East.function([], IntegerType, $ => {
+     *     return Time.now();
+     * });
+     *
+     * const compiled = await East.compileAsync(getTimestamp.toIR(), Time.Implementation);
+     * await compiled();  // Returns: 1735689600000n (example timestamp)
+     * ```
+     */
+    now: time_now,
+    /**
+     * Sleeps for the specified number of milliseconds.
+     *
+     * Pauses execution asynchronously for the given duration. Non-blocking sleep
+     * that allows other operations to run during the wait period.
+     *
+     * @param ms - The number of milliseconds to sleep (must be non-negative)
+     * @returns Null after sleeping completes
+     * @throws {EastError} When sleep fails
+     *
+     * @example
+     * ```ts
+     * const delayedTask = East.function([], NullType, $ => {
+     *     $(Console.log("Starting..."));
+     *     $(Time.sleep(1000n));
+     *     $(Console.log("Done!"));
+     * });
+     *
+     * const compiled = await East.compileAsync(delayedTask.toIR(), Time.Implementation);
+     * await compiled();  // Waits 1 second between log messages
+     * ```
+     */
+    sleep: time_sleep,
+    /**
+     * Gets the UTC offset in minutes for an IANA timezone at a given UTC datetime.
+     *
+     * Accounts for DST — the same timezone returns different offsets depending
+     * on the datetime. Use the result with `addMinutes` to convert a UTC datetime
+     * to local time.
+     *
+     * @param datetime - A UTC datetime
+     * @param zone - An IANA timezone name (e.g., "Australia/Sydney")
+     * @returns UTC offset in minutes
+     * @throws {EastError} When the timezone name is invalid
+     *
+     * @example
+     * ```ts
+     * const toSydneyTime = East.function([DateTimeType], DateTimeType, ($, dt) => {
+     *     const offset = $.let(Time.getTimezoneOffset(dt, "Australia/Sydney"));
+     *     $.return(dt.addMinutes(offset));
+     * });
+     * ```
+     */
+    getTimezoneOffset: time_get_timezone_offset,
+    /**
+     * Browser implementation of time platform functions.
+     *
+     * Pass this to {@link East.compileAsync} to enable time operations.
+     */
+    Implementation: TimeImpl,
+};
+// Exported beside `Time.Implementation`, as east-node-std exports it
+export { TimeImpl };
+//# sourceMappingURL=time.js.map

package/dist/src/time.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"time.js","sourceRoot":"","sources":["../../src/time.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@elaraai/east-web-std",
+  "version": "1.0.85",
+  "description": "East Web - the standard platform functions for East programs in a browser",
+  "main": "dist/src/index.js",
+  "types": "dist/src/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/src/index.d.ts",
+      "default": "./dist/src/index.js"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist/src",
+    "!dist/**/*.spec.*",
+    "README.md",
+    "LICENSE.md",
+    "CONTRIBUTING.md",
+    "CLA.md",
+    "THIRD_PARTY_NOTICES.md"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/elaraai/east-workspace.git",
+    "directory": "libs/east-web/packages/east-web-std"
+  },
+  "keywords": [
+    "east",
+    "elara",
+    "browser",
+    "web",
+    "platform",
+    "runtime"
+  ],
+  "author": "Elara AI Pty Ltd",
+  "license": "AGPL-3.0-or-later",
+  "type": "module",
+  "engines": {
+    "node": ">=22.0.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.18.1",
+    "@typescript-eslint/eslint-plugin": "^8.42.0",
+    "@typescript-eslint/parser": "^8.42.0",
+    "eslint": "^9.34.0",
+    "eslint-plugin-headers": "^1.3.3",
+    "typescript": "~5.9.2",
+    "@elaraai/east-node-std": "1.0.85"
+  },
+  "peerDependencies": {
+    "@elaraai/east": "1.0.85"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "package": "npm run build && mkdir -p .package && npm pack --pack-destination .package",
+    "test": "npm run build && node --enable-source-maps --test-reporter=spec --test 'dist/test/**/*.spec.js'",
+    "test:check": "tsc -p tsconfig.test.json",
+    "test:coverage": "npm run build && node --enable-source-maps --test-reporter=spec --test --experimental-test-coverage 'dist/test/**/*.spec.js'",
+    "test:compliance": "npm run build && node --enable-source-maps --test-reporter=spec --test dist/src/compliance.spec.js",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix"
+  }
+}