@ayonli/jsext
Version:
A JavaScript extension package for building strong and modern applications.
233 lines (232 loc) • 7.33 kB
TypeScript
/**
* Utility functions to retrieve runtime information or configure runtime behaviors.
* @module
* @experimental
*/
/// <reference types="node" />
export type WellknownRuntime = "node" | "deno" | "bun" | "workerd" | "fastly" | "chrome" | "firefox" | "safari";
/**
* @deprecated
*/
export declare const WellknownRuntimes: WellknownRuntime[];
/**
* The information of the runtime environment in which the program is running.
*/
export interface RuntimeInfo {
/**
* A string identifying the runtime.
*/
identity: WellknownRuntime | "unknown";
/**
* The version of the runtime. This property may be `undefined` if the
* runtime doesn't provide version information, or when the runtime is
* `unknown`.
*/
version?: string | undefined;
/**
* Whether the runtime has file system support. When `true`, the program can
* use the `@ayonli/jsext/fs` module to access the file system.
*/
fsSupport: boolean;
/**
* Whether the runtime has TypeScript support. When `true`, the program can
* import TypeScript files directly.
*/
tsSupport: boolean;
/**
* If the program is running in a worker thread, this property indicates the
* type of the worker.
*/
worker?: "dedicated" | "shared" | "service" | undefined;
}
/**
* Returns the information of the runtime environment in which the program is
* running.
*
* @example
* ```ts
* import runtime from "@ayonli/jsext/runtime";
*
* console.log(runtime());
*
* // In Node.js
* // {
* // identity: "node",
* // version: "22.0.0",
* // fsSupport: true,
* // tsSupport: false,
* // worker: undefined
* // }
*
* // In Deno
* // {
* // identity: "deno",
* // version: "1.42.0",
* // fsSupport: true,
* // tsSupport: true,
* // worker: undefined
* // }
*
* // In the browser (Chrome)
* // {
* // identity: "chrome",
* // version: "125.0.0.0",
* // fsSupport: true,
* // tsSupport: false,
* // worker: undefined
* // }
*
* // ...
* ```
*/
export default function runtime(): RuntimeInfo;
export type WellknownPlatform = "darwin" | "windows" | "linux" | "android" | "freebsd" | "openbsd" | "netbsd" | "aix" | "solaris";
/**
* @deprecated
*/
export declare const WellknownPlatforms: WellknownPlatform[];
/**
* Returns a string identifying the operating system platform in which the
* program is running.
*/
export declare function platform(): WellknownPlatform | "unknown";
/** Returns all environment variables in an object. */
export declare function env(): {
[name: string]: string;
};
/** Returns a specific environment variable. */
export declare function env(name: string): string | undefined;
/**
* Sets the value of a specific environment variable.
*
* @deprecated The program should not try to modify the environment variables,
* and it's forbidden in worker environments.
*/
export declare function env(name: string, value: string): undefined;
/**
* Sets the values of multiple environment variables, could be used to load
* environment variables where there is no native support, e.g the browser or
* Cloudflare Workers.
*/
export declare function env(obj: object): void;
/**
* Detects if the program is running in a REPL environment.
*
* NOTE: This function currently returns `true` when in:
* - Node.js REPL
* - Deno REPL
* - Bun REPL
* - Google Chrome Console
*/
export declare function isREPL(): boolean;
/**
* Make the timer block the event loop from finishing again after it has been
* unrefed.
*
* NOTE: This function is only available in Node.js, Deno and Bun, in other
* environments, it's a no-op.
*/
export declare function refTimer(timer: NodeJS.Timeout | number): void;
/**
* Make the timer not block the event loop from finishing.
*
* NOTE: This function is only available in Node.js, Deno and Bun, in other
* environments, it's a no-op.
*
* @example
* ```ts
* import { unrefTimer } from "@ayonli/jsext/runtime";
*
* const timer = setTimeout(() => {
* console.log("Hello, World!");
* }, 1000);
*
* unrefTimer(timer);
* ```
*/
export declare function unrefTimer(timer: NodeJS.Timeout | number): void;
/**
* Adds a listener function to be called when the program receives a `SIGINT`
* (`Ctrl+C`) signal, or a `shutdown` message sent by the parent process (a
* **PM2** pattern for Windows), so that the program can perform a graceful
* shutdown.
*
* This function can be called multiple times to register multiple listeners,
* they will be executed in the order they were added, and any asynchronous
* listener will be awaited before the next listener is executed.
*
* Inside the listener, there is no need to call `process.exit` or `Deno.exit`,
* the program will exit automatically after all listeners are executed in order.
* In fact, calling the `exit` method in a listener is problematic and will
* cause any subsequent listeners not to be executed.
*
* The listener function receives a {@link CloseEvent}, if we don't what the program
* to exit, we can call `event.preventDefault()` to prevent from exiting.
*
* In the browser or unsupported environments, this function is a no-op.
*
* @example
* ```ts
* import { addShutdownListener } from "@ayonli/jsext/runtime";
* import { serve } from "@ayonli/jsext/http";
*
* const server = serve({
* fetch(req) {
* return new Response("Hello, World!");
* }
* });
*
* addShutdownListener(async () => {
* await server.close();
* });
* ```
*/
export declare function addShutdownListener(fn: (event: CloseEvent) => void | Promise<void>): void;
/**
* Adds a listener function to be called when an unhandled promise rejection
* occurs in the program, this function calls
* `addEventListener("unhandledrejection")` or `process.on("unhandledRejection")`
* under the hood.
*
* The purpose of this function is to provide a unified way to handle unhandled
* promise rejections in different environments, and when possible, provide a
* consistent behavior of the program when an unhandled rejection occurs.
*
* By default, when an unhandled rejection occurs, the program will log the
* error to the console (and exit with a non-zero code in Node.js, Deno and Bun),
* but this behavior can be customized by calling `event.preventDefault()` in
* the listener function.
*
* In unsupported environments, this function is a no-op.
*
* @example
* ```ts
* import { addUnhandledRejectionListener } from "@ayonli/jsext/runtime";
*
* addUnhandledRejectionListener((event) => {
* console.error(event.reason);
* event.preventDefault(); // Prevent default logging and exiting behavior
* });
* ```
*/
export declare function addUnhandledRejectionListener(fn: (event: PromiseRejectionEvent) => void): void;
/**
* A unified symbol that can be used to customize the inspection behavior of an
* object, currently supports Node.js, Bun and Deno.
*
* @example
* ```ts
* import { customInspect } from "@ayonli/jsext/runtime";
*
* class Point {
* constructor(public x: number, public y: number) {}
*
* [customInspect]() {
* return `Point (${this.x}, ${this.y})`;
* }
* }
*
* console.log(new Point(1, 2)); // Point (1, 2)
* ```
*/
export declare const customInspect: unique symbol;