ranuts API（自动生成）

由 bin/generate-api-docs.ts（npm run doc:api）自动生成：按入口点列出每一个导出符号的签名与一行描述。描述直接提取自源码 JSDoc，因此保持英文。使用指引（该从哪个入口导入、运行环境约束、约定）请先阅读 CLAUDE.md。

请从符号所属的子路径导入，例如 import { debounce } from 'ranuts/utils'。根入口 ranuts 重新导出 utils + visual 的全部符号。

413 个导出，共 6 个入口点。生成时间 2026-08-18T13:16:54.528Z。

入口点

ranuts/utils — 浏览器与通用工具函数 · 浏览器 + node · 327 个导出
ranuts/sw — Service Worker 缓存策略与预缓存协议 · 仅 service worker · 9 个导出
ranuts/node — Node 服务端工具（fs / http / ws / 中间件） · 仅 node · 26 个导出
ranuts/visual — 2D 渲染引擎（Canvas / WebGL / WebGPU） · 仅浏览器 · 16 个导出
ranuts/i18n — 框架无关的 i18n 引擎（也从 ranuts/utils 再导出） · 浏览器 + node · 9 个导出
ranuts/vnode — Snabbdom 风格的虚拟 DOM · 浏览器 · 26 个导出

`ranuts/utils`

浏览器与通用工具函数 · 运行环境：浏览器 + node · 源码：src/utils/index.ts

import { /* … */ } from 'ranuts/utils';

函数

acceptPortBridge({ targetOrigin, name, }?: AcceptPortBridgeOptions) => Promise<PortBridge> — Acceptor: wait for the port the initiator hands over and return the bridge once the
addClassToElement(element: Element, addClass: string) => void — Add a class to an element
addNumSym(value: string | number, flag?: string | number) => string
adoptSheetText(shadowRoot: ShadowRoot, cssText: string, marker?: string) => void — Inject dynamic styles supplied at runtime (a component's sheet property, say).
adoptStyles(shadowRoot: ShadowRoot, cssText: string, marker?: string) => void — Inject a component's static styles into a shadow root.
appendUrl(url: string, params?: Record<string, string>) => string — Turn an object into a query string and append it to a URL
arrayBufferToString(buffer: ArrayBuffer | Uint8Array) => string — Decode bytes into a string using the sniffed encoding. Required when reading
autosizeTextarea(element: HTMLTextAreaElement) => (() => void) — Make a <textarea> grow and shrink with its content, so a long message is
base64ToBytes(base64: string) => Uint8Array<ArrayBuffer> — Decode base64 into bytes. Accepts a bare payload or a full
base64UrlToBytes(value: string) => Uint8Array | null — Decode base64url back into bytes, restoring the padding the encoder dropped.
blendMultiply(base: RGB, blend: RGB) => RGB — Multiply blend of two colours (channel-wise base * blend). Channels in 0..1.
blendOverlay(base: RGB, blend: RGB) => RGB — Overlay blend of two colours (multiply in shadows, screen in highlights). Channels in 0..1.
blendScreen(base: RGB, blend: RGB) => RGB — Screen blend of two colours (channel-wise 1 - (1 - base)(1 - blend)). Channels in 0..1.
brightnessContrast(color: RGB, brightness: number, contrast: number) => RGB — Adjust brightness and contrast of a colour: (c - 0.5) * contrast + 0.5 + brightness per channel. Channels in 0..1.
buildOffsets(lengths: readonly number[]) => number[] — The global start offset of every chunk in the concatenated coordinate
bytesToBase64(data: Uint8Array | ArrayBuffer) => string — Encode bytes as base64 without blowing the call stack.
bytesToBase64Url(data: Uint8Array | ArrayBuffer) => string — Encode bytes as base64url — the URL- and filename-safe alphabet from RFC 4648
checkEncoding(uint8Array: Uint8Array) => string
clamp(value: number, min: number, max: number) => number — Clamp value into the inclusive range [min, max].
clearBr(str?: string) => string — Strip whitespace, line breaks and HTML tags out of a string
clearStr(str: string, options?: ClearStrOption) => string — Trim surrounding whitespace, percent-decode, and drop surrounding quotes
cloneDeep<T>(value: T, cloneMap?: WeakMap<object, any>) => T — Deep clone, covering the complex built-in types and circular references.
componentToHex(c: string | number) => string
compose<T>(middleware: Array<Middleware<T>>) => ComposedMiddleware<T> — Run a chain of async functions as if it were sequential
computePlacement(options: ComputePlacementOptions) => ComputedPlacement — Position a floating panel relative to an anchor rect: flips to the opposite
concatBytes(chunks: readonly Uint8Array[]) => Uint8Array — Join byte chunks into one buffer, in order.
connection() => number | undefined — Current network status: type, throughput, and whether the connection changed
convertImageToBase64(file: File) => Promise<convertImageToBase64Return> — Convert an image to base64
cosinePalette(t: number, a: RGB, b: RGB, c: RGB, d: RGB) => RGB — Inigo Quilez cosine gradient palette: a + b * cos(2π(c·t + d)). Each of a,b,c,d is an RGB triple; t is the position 0..1. Returns an RGB triple.
crc32(data: Uint8Array) => number — CRC32 checksum (IEEE 802.3 polynomial), the one ZIP stores per entry.
create(tagName: string, options?: ElementCreationOptions) => Chain
createData(params?: Record<string, unknown>) => Record<string, unknown> — Build the standard envelope that accompanies a report — page URL, referrer,
createDocumentFragment(list: Element[]) => DocumentFragment | undefined — Create a DocumentFragment
createDoubleTapDetector(options?: DoubleTapDetectorOptions) => DoubleTapDetector — Double-tap detection over raw (x, y, time) samples — pointer-type-agnostic,
createHandoff<T>({ dbName, storeName, key }: HandoffOptions) => Handoff<T> — A one-shot value handoff between two pages of the same origin, backed by
createI18n<TDict extends StringValues<TDict> = MessageDict>(config?: I18nConfig<TDict>) => I18nCore<TDict> — Create and register the global i18n singleton.
createLocalePath(config: LocalePathConfig) => LocalePath — Create the set of locale path conversion functions.
createObjectURL(src: Blob | ArrayBuffer | Response) => Promise<string>
createPortBridge(port: MessagePort) => PortBridge — Build a bridge on any MessagePort (a Web Worker, a SharedWorker, or a port from a completed handshake).
createRaceGuard() => RaceGuard — Bump-and-compare guard against a stale async response overwriting a newer
createSignal<T = unknown>(value: T, options?: SignalOptions<T>) => [() => T, (newValue: T) => void] — Create a minimal signal with optional event broadcasting, returned as
createSpeechRecognizer(options?: SpeechRecognizerOptions) => SpeechRecognizer — Create a dictation session over the Web Speech API.
createStore<T>(prefix?: string) => JsonStore<T> — A prefixed, JSON-serialising view over localStorage.
createZip(files: ReadonlyArray<{ name: string; data: Uint8Array | string; }>) => Uint8Array — Build a ZIP from scratch, every entry STORED. No compression, so this is
csvEscape(value: string | number) => string — Escape one CSV field: doubles any quote and wraps the value when it contains
currentDevice() => CurrentDevice
cutRound(img: ImgSource, radius: number) => ImgSource — Round an image's corners, returning an offscreen canvas.
debounce<T extends (...args: any[]) => any>(fn: T, ms?: number) => Debounced<T> — Debounce — on a burst of calls, run only the last one, **ms milliseconds
decodeTextBytes(bytes: Uint8Array, encodings?: string[]) => string — Decode text bytes, trying encodings in order until one holds.
deferred<T = void>() => Deferred<T> — A promise plus its resolve / reject, for the case where the thing that
delay(ms: number) => Promise<void> — Resolve after ms milliseconds. Uses the bare setTimeout, so it works in
detectLanguage(text: string, sampleSize?: number) => TextLanguage — Decide a text's primary language from the ratio of CJK to Latin characters.
durationHandler<T, U>(handler: (...args: T[]) => U, ...params: T[]) => ((a: number) => Promise<U>) — Run a function repeatedly at a fixed interval
encodeUrl(url: string) => string — Encode a URL to a percent-encoded form, excluding already-encoded sequences.
escapeHtml(string?: string | number | null) => string
fanShapedByArc(ctx: CanvasRenderingContext2D, maxRadius: number, start: number, end: number, gutter: number) => void — Trace a pie slice with arc(), including the gutter between slices.
fenceCode(body: string, lang?: string) => string — Wrap text in a Markdown code fence long enough to survive backticks inside it.
fetchMaybeGzip(input: RequestInfo | URL, init?: RequestInit) => Promise<Uint8Array> — Fetch a resource that may be delivered gzipped or already
filterObj(obj: Record<string, unknown>, list: Array<string>) => Record<string, unknown> — Return a new object without the properties whose values appear in list — typically used to drop empty strings and nulls
fit(value: number, a1: number, a2: number, b1: number, b2: number) => number — Remap value from [a1, a2] onto [b1, b2] and clamp to the output range — the shader fit.
formatDate(value?: DateInput, pattern?: string) => string — Format a date with a token pattern. Accepts a timestamp, a date string, a
formatDuration(seconds: number) => string — Format an elapsed number of seconds as a colon-separated clock duration,
formatJson(value: string | object, onError?: (error: Error) => void, indent?: number) => string — Pretty-print JSON. Accepts an object or a JSON string (single quotes are
formatRelative(value: DateInput, options?: FormatRelativeOptions) => string — Format a point in time relative to another — "3 days ago", "in 2 hours".
getAllQueryString(url?: string) => Record<string, string> — Parse a URL's query string into an object. Defaults to the current
getAngle(deg: number) => number — Degrees to radians
getArcPointerByDeg(deg: number, r: number) => [number, number] — The point on a circle at a given angle
getCookie(objName: string) => string — Read a named cookie
getCookieByName(name: string) => string
getExtensions(mimeType: string) => string[] — Get file extensions from MIME type
getFrame(n?: number) => Promise<number> — Frames per millisecond; multiply by 1000 for frames per second
getImage(src: string) => Promise<ImgSource> — Load an image by path, resolving once it has decoded.
getLinearGradient(ctx: CanvasRenderingContext2D, x: number, y: number, w: number, h: number, background: string) => CanvasGradient — Translate a CSS linear-gradient(...) string into a Canvas CanvasGradient.
getMatchingSentences(text: string, searchValue: string) => string[] — Collect the complete sentences of a text that contain the search term, keeping only the
getMatrix(radius: number, sigma?: number) => number[] — Build a 2D Gaussian weight matrix, normalised so the weights sum to 1.
getMime(ext: string) => string | undefined
getPerformance() => BasicType | undefined
getPixelRatio(context: CanvasRenderingContext2D & Partial<Context>) => number — Get the device pixel ratio
getRandomString(len?: number) => string — A short random-ish base-36 string.
getReportUrl() => string — The currently configured reporting endpoint, or '' when none was set
getStatus(code?: number | string) => number | string | undefined — Get the status code.
getTangentByPointer(x: number, y: number) => Array<number> — The tangent line at a point on a circle
getWindow() => ClientRatio — Get the viewport size across browsers
gunzipMaybe(bytes: Uint8Array) => Promise<Uint8Array> — Decompress bytes if — and only if — they are still gzipped.
handleConsole(hooks?: (...args: unknown[]) => void) => (() => void) — Tap into console so every call also reaches your hook, while still printing
handleError(hooks?: (error: ErrorPayload) => void) => (() => void) — Listen for uncaught errors and unhandled promise rejections, in the capture
handleFetchHook(options?: Partial<Options>) => (() => void) — Instrument window.fetch so every request, response and failure reaches your
handleXhrHook(options?: Partial<Options>) => (() => void) — Instrument XMLHttpRequest (open / send) so requests, responses and
hexToAlpha(aa: string) => number — A two-digit hex alpha channel (ff / 80 / 00) to a 0–100 percentage.
hexToHsb(hex: string) => number[] | null — #rrggbb / #rgb to [h, s, b]; null when the hex is invalid.
hexToHsv(hex: string) => number[] | null
hexToRgb(hex: string) => Array<number> | null — #rrggbb / #rgb (with or without the #) to [r, g, b]; null when it cannot be parsed.
hsbToHsl(h: number, s: number, b: number) => number[]
hsbToRgb(h: number, s: number, v: number) => number[]
hslToHsb(h: number, s: number, l: number) => number[] — [h, s, l] to [h, s, b]
hslToHsv(h: number, s: number, l: number) => number[]
hslToRgb(h: number | string | number[], s: number | string, l: number | string) => Array<number>
hsvToHsl(h: number, s: number, b: number) => number[]
hsvToRgb(h: number, s: number, v: number) => number[]
hue2rgb(p: number, q: number, t: number) => number
imageRequest(url?: string) => Promise<number> — Request an image (used to time the network)
indexForOffset(offsets: readonly number[], offset: number) => number — Binary-search which chunk a global offset falls into — the last index
inflateRaw(data: Uint8Array) => Promise<Uint8Array> — Decompress raw DEFLATE bytes (no zlib or gzip wrapper) — the form ZIP
inverseLerp(a: number, b: number, value: number) => number — Inverse of lerp — where value sits between a and b, as 0..1. Returns 0 when a === b. Not clamped.
isEqual(value: any, other: any, seen?: Map<any, any>) => boolean — Deep-compare two values.
isGzip(bytes: Uint8Array) => boolean — Whether the bytes start with the gzip magic number (1f 8b).
isHtmlDocument(bytes: Uint8Array) => boolean — Whether the bytes are an HTML document rather than the binary
isImageSize(file: File, width?: number, height?: number) => Promise<boolean> — Check an image's dimensions against a given width / height. When both are
isInIframe() => boolean — Whether this page is running inside an iframe. Returns false under SSR.
isMobile() => boolean — Whether this is a mobile device
isSafari() => boolean | undefined | string
isSpeechRecognitionSupported() => boolean — Whether this runtime can recognize speech. Checked at call time, so it is safe
isString(obj: unknown) => boolean
isUrlCached(url: string) => Promise<boolean> — Whether a URL is already in CacheStorage. When probing a group of files,
isWeiXin() => boolean — Whether this is the WeChat in-app browser
isZipContainer(bytes: Uint8Array) => boolean — Whether the bytes are a ZIP container (PK\x03\x04) — which is
lerp(a: number, b: number, t: number) => number — Linear interpolation from a to b by t (t=0 → a, t=1 → b). Not clamped.
linearstep(edge0: number, edge1: number, x: number) => number — Linear ramp — 0 below edge0, 1 above edge1, a straight line between (the shader linearstep, no smoothing).
linearToSrgb(c: number) => number — Convert one linear-light channel (0..1) to sRGB.
loadScript({ type, content }: LoadScriptOptions) => Promise<{ success: boolean; }> — Inject one script dynamically, de-duplicated by content.
localStorageGetItem(name: string) => string — Read a string from localStorage, or '' when missing or unavailable.
localStorageRemoveItem(name: string) => void — Remove a key from localStorage. Silently does nothing when storage is unavailable.
localStorageSetItem(name: string, value: string) => void — Write a string to localStorage. Silently does nothing when storage is
luma(r: number, g: number, b: number) => number — Perceived brightness (luma) of an RGB colour using Rec. 601 weights. Channels may be 0..1 or 0..255 — the result keeps that scale.
matchMediaQuery(query: string) => boolean — Read whether a media query currently matches, synchronously. Returns false under SSR.
mathjs(a: number, type: string, b: number) => ComputeNumberResult
md5(str: string) => string — MD5 hash function implementation
memoize<T extends Func>(fn: T | unknown) => ((...args: Parameters<T>) => ReturnType<T>) — Former name of once. The name is misleading — it does not cache per
merge(a: Obj, b?: Obj) => Obj — Merge objects
mergeExports(obj: Record<string, string>, exports: Record<string, string>) => Record<string, string> — Copy an exports object onto obj, then freeze it
navigatorLanguage() => TextLanguage — Map the browser UI language into the same buckets (the default when there is
networkAllowsDownload(options?: NetworkAllowanceOptions) => boolean — Whether the current network and user settings allow proactively downloading
networkSpeed(options: Options) => Promise<ReturnType> — Measure the network's ping by timing requests
noop() => void
once<T extends Func>(fn: T | unknown) => ((...args: Parameters<T>) => ReturnType<T>) — Run once — evaluate on the first call, cache the result, and return that
opacity(img: ImgSource, opacity: number) => ImgSource — Apply an overall opacity to an image, returning an offscreen canvas.
openPortBridge({ targetWindow, targetOrigin, name, }: OpenPortBridgeOptions) => PortBridge — Initiator: create a MessageChannel, hand one port to the target window and keep the other.
paginateText(text: string, box: TextBox, metrics: TextGridMetrics, options?: PaginateOptions) => PaginateResult — Cut text into pages that fit box, given the type metrics.
parseChineseNumber(value: string) => number | null — Chinese numerals to Arabic, covering 「十五」「二十三」「一百零三」「一千零一」「三万」.
parseEnglishNumber(value: string) => number | null — English ordinals to numbers, tried in order: Arabic digits, number words
parseRomanNumber(value: string) => number | null — Roman numerals to Arabic (either case, handling subtractive forms such as IV / IX). Returns null for invalid input.
parseVttCueTiming(line: string) => { start: number; end: number; } | undefined — Parse a WebVTT cue timing line — <start> --> <end>, optionally followed by
parseVttTimestamp(raw: string) => number | undefined — Parse a WebVTT/SRT-style timestamp — HH:MM:SS.mmm or MM:SS.mmm (the hour
performanceTime() => number — Current timestamp
perToNum(str?: string) => number — Convert a percentage string into a number
prefetchUrl(url: string) => Promise<void> — Pull a single URL into the cache; skipped when already cached. Failures are
prefetchUrls(urls: string[], options?: PrefetchOptions) => Promise<void> — Prefetch a group of URLs, serially — prefetching is background work, and
prefetchWhenIdle(urls: string[], options?: WhenIdleOptions & NetworkAllowanceOptions & PrefetchOptions) => (() => void) — Prefetch a group of URLs while idle, subject to networkAllowsDownload.
queryFlag(key: string, url?: string) => boolean — Read a query parameter as a boolean flag. True for ?k, ?k=, ?k=1 and
querystring(data?: {}) => string — Serialise an object into a URL query string
randomColor() => Color
randomString(len?: number) => string — A short random-ish string prefixed with the current timestamp.
range(num: number, min?: number, max?: number) => number — Clamp a value between a minimum and a maximum
readFileAsArrayBuffer(blob: Blob) => Promise<ArrayBuffer> — Read a File / Blob as an ArrayBuffer
readFileAsDataURL(blob: Blob) => Promise<string> — Read a File / Blob as a data: URL (image previews and the like)
readFileAsText(blob: Blob, encoding?: string) => Promise<string> — Read a File / Blob as text
readFileAsUint8Array(blob: Blob) => Promise<Uint8Array<ArrayBuffer>> — Read a File / Blob as a Uint8Array (pair with checkEncoding / arrayBufferToString for encoding sniffing)
readZipEntries(bytes: Uint8Array) => ZipEntry[] — Read an archive's central directory. Returns [] for anything that is not
readZipEntry(bytes: Uint8Array, entry: string | ZipEntry) => Promise<Uint8Array | null> — Extract one entry's decompressed bytes. Resolves null when the entry is
remap(value: number, a1: number, a2: number, b1: number, b2: number) => number — Linearly remap value from range [a1, a2] onto [b1, b2]. Not clamped (GLSL-style map).
removeClassToElement(element: Element, removeClass: string) => void — Remove a class from an element
replaceOld(source: any, name: string, replacement: (...args: unknown[]) => unknown, isForced?: boolean) => () => void — Replace a property on an object, wrapping whatever was there before.
report({ url, type, payload }: BeaconPayload) => boolean — Send a telemetry beacon. Prefers navigator.sendBeacon (does not block
requestUrlToBuffer(src: string, options: Partial<RequestUrlToArraybufferOption>) => Promise<requestUrlToArraybufferReturn> — Fetch a URL as an ArrayBuffer
resolveLocale(options: ResolveLocaleOptions) => string — Resolve which of your supported locales to use, from the usual chain:
rewriteZip(bytes: Uint8Array, options?: RewriteZipOptions) => Promise<Uint8Array> — Rebuild an archive with some entries replaced and/or new entries appended.
rgbaString(r: number, g: number, b: number, a: number) => string — Build a CSS rgba() string. Alpha is 0–100 rather than 0–1, matching the
rgbaToHex(r: number, g: number, b: number, a: number) => string — Composite a translucent colour over white and return it as a 6-digit hex.
rgbaToRgb(r: number, g: number, b: number, a: number) => number[] — Composite a translucent colour over white, giving the equivalent opaque rgb.
rgbToHex(r: string | number | Array<string | number>, g?: string | number, b?: string | number) => string
rgbToHsb(r: number, g: number, b: number) => number[]
rgbToHsl(r: number | number[], g?: number, b?: number) => Array<number>
rgbToHsv(r: number, g: number, b: number) => number[] — Alias of rgbToHsb — HSV and HSB are two names for the same colour space.
roundRectByArc(ctx: CanvasRenderingContext2D, ...[x, y, w, h, r]: number[]) => void — Trace a rounded rectangle with arc(). A corner radius larger than half the
safeEqual(a: string | Uint8Array, b: string | Uint8Array) => boolean — Compare two secrets in time that does not depend on where they first differ.
saturation(color: RGB, amount: number) => RGB — Adjust saturation by mixing toward the colour's luminance. amount 0 = greyscale, 1 = unchanged, >1 = more saturated. Channels in 0..1.
saveFileToDisk(data: Blob | Uint8Array, fileName: string, options?: SaveFileOptions) => Promise<boolean> — Save bytes to disk: a real "Save as" dialog through the File
scriptOnLoad(urls: string[], append?: HTMLElement, callback?: () => void) => Promise<void> — Insert script/link tags dynamically
secureRandomString(length: number, alphabet?: string) => string — A random string drawn from alphabet using the platform CSPRNG.
secureToken(bytes?: number) => string — A random hex token of bytes bytes, from the platform CSPRNG.
segmentByRanges<T>(text: string, chunkStart: number, ranges: readonly OffsetRange<T>[]) => Segment<T>[] — Split one chunk of text into a sequence of plain / matched spans according
serveWorker<Req extends WorkerRequestBase, Res extends object = object, Progress = unknown>(handler: (request: Req, context: WorkerHandlerContext<Progress>) =>… — Serve requests inside a Web Worker, mirroring {@link WorkerClient} on the
setFontSize2html(designWidth?: number) => void — Set the root font size from the design mock's width
setMime(ext: string, mimeType: string) => Map<string, string>
setReportUrl(next: ReportConfig | string) => void — Configure the default reporting endpoint (and optionally the cookie holding
singleFlight<T>(fn: () => Promise<T>) => SingleFlight<T> — The async flavour of "run once": concurrent callers share one in-flight
slugify(text: string, maxLength?: number) => string — Reduce text to a lowercase a-z0-9- slug, safe as a filename on every
smoothstep(edge0: number, edge1: number, x: number) => number — Smooth Hermite interpolation between 0 and 1 for edge0 < x < edge1 (GLSL smoothstep).
srgbToLinear(c: number) => number — Convert one sRGB channel (0..1) to linear-light (IEC 61966-2-1 transfer function).
strParse(str?: string, sep?: string | RegExp, eq?: string | RegExp) => Record<string, string> — Parse a delimited string into an object, e.g.
throttle<T extends (...args: any[]) => any>(fn: T, delay?: number) => Throttled<T> — Throttle — under a burst of calls, run at a fixed interval: the first call
timeFormat(time: number) => string — Format a number of seconds as a colon-separated duration
timestampToTime(timestamp?: number | string) => Date & { format?: Function; } — Turn a timestamp into a Date carrying a format method.
toFullWidth(value: string) => string — Convert half-width characters to full-width (the inverse of toHalfWidth)
toHalfWidth(value: string) => string — Convert full-width characters to half-width (digits, letters, punctuation and
toString(value: string | number) => string
transformNumber(value: string, locale?: string, precision?: number, fixed?: number) => string
transformText(content: string | ArrayBuffer) => TransformText | undefined
truncate(value: string, options: TruncateOptions | number) => string — Shorten a string to a maximum length, marking the cut with an ellipsis.
truncateWithMarker(text: string, max: number, marker?: string) => string — Cut text to max characters and mark that it was cut.
useI18n<TDict extends StringValues<TDict> = MessageDict>() => I18nCore<TDict> | null — The active global instance, or null when none was created. Pass the same
vibrance(color: RGB, amount: number) => RGB — Vibrance — saturates muted colours more than already-saturated ones. amount > 0 boosts, < 0 mutes. Channels in 0..1.
watchMediaQuery(query: string, callback: (matches: boolean) => void) => (() => void) — Watch a media query. The callback **fires once synchronously with the
whenIdle(callback: () => void, options?: WhenIdleOptions) => (() => void) — Run a callback while the browser is idle, falling back to setTimeout where
withTimeout<T>(promise: Promise<T>, ms: number, options?: { message?: string; onTimeout?: () => void; }) => Promise<T> — Reject if a promise has not settled within ms. The returned promise
withTimeoutFallback<T>(promise: Promise<T>, ms: number, fallback: T, onTimeout?: () => void) => Promise<T> — Resolve to a fallback value instead of rejecting when ms elapses. For
zipHasEntry(bytes: Uint8Array, name: string) => boolean — Whether the archive contains an entry with exactly this name. Cheaper than

类

class AudioRecorder — Record audio
class BridgeManager
class Chain — Chainable DOM operations
class Color
class ColorScheme
class EventManager — EventManager — a scoped listener registry built on AbortController.
class Hsl
class Hsla
class I18nCore — The engine. Optionally parameterised by your dictionary shape.
class Mathjs — Arithmetic that works around floating-point precision.
class Monitor — Front-end telemetry: page-load performance, clicks, errors, fetch/XHR traffic
class PostMessageBridge — Bridge registration event, consumed by the client
class QuestQueue — An async task queue with limited concurrency. At most simultaneous tasks
class Rgb
class Rgba
class SyncHook
class TimeoutError
class TOTP
class WebDB — A Promise wrapper over IndexedDB. The native API is event-callback and
class WorkerClient — A worker client with request ids. The request type Req is defined by the

接口

interface AcceptPortBridgeOptions
interface BeaconPayload
interface BridgeManagerOptions
interface BroadcastPayload
interface CallToPayload
interface ComputedPlacement
interface ComputePlacementOptions
interface Debounced
interface Deferred — Promise primitives that JavaScript does not ship: an externally settled promise and a
interface DoubleTapDetector
interface DoubleTapDetectorOptions
interface FormatRelativeOptions
interface Handoff
interface HandoffOptions
interface I18nConfig
interface IDBCollection — A store name bound once, values unwrapped, failures folded into the empty case
interface IDBResult — The uniform result shape of every IndexedDB operation. Every method
interface IDBStoreSchema — Declarative schema for object stores. openDataBase creates the missing
interface JsonStore
interface LoadScriptOptions
interface LocalePath
interface LocalePathConfig
interface LocaleRoute — URL maths for a multi-language site (pure functions, no global state, no DOM).
interface MessageData
interface MessageHandler
interface NetworkAllowanceOptions
interface OffsetRange — An annotation in global coordinates: the half-open interval [start, end) plus any payload
interface OpenPortBridgeOptions
interface PaginateOptions
interface PaginateResult
interface PendingRequest
interface PlacementRect
interface PortBridge — A point-to-point bridge over MessagePort.
interface PrefetchOptions
interface RaceGuard
interface ReportConfig
interface ResolveLocaleOptions
interface RewriteZipOptions
interface Segment — One piece of the split result: value === null marks a plain span covered by no range
interface ServeWorkerOptions
interface SingleFlight
interface SpeechError
interface SpeechRecognizer
interface SpeechRecognizerOptions
interface SpeedType — The ease-in / ease-out pair of one easing family
interface TextBox — The box each page must fit into, in px.
interface TextGridMetrics
interface TextPage
interface Throttled
interface TransformText
interface TruncateOptions
interface WebDBOptions
interface WhenIdleOptions
interface WorkerClientOptions
interface WorkerHandlerContext — Handed to the handler so it can stream progress for the request it is currently serving
interface WorkerRequestBase — A request always carries the id the client stamped on it
interface WorkerResponseBase — A response must at least echo the request id so the two can be paired
interface ZipEntry — One entry as described by the archive's central directory.

类型

type CurrentDevice
type DateInput — Accepted everywhere a moment in time is taken; undefined means "now".
type EasingFn — One easing function: (elapsed, from, delta, duration) => current value
type ImgSource — A bitmap container usable both as a drawImage source and as a render target
type LocaleChangeHandler
type LocaleMessages — Locale → dictionary. Parameterised by the dictionary shape so an app can hand in its own
type MessageDict
type Placement
type RelativeStyle — 'compact' is ours; the other three are Intl.RelativeTimeFormat styles.
type RGB — An RGB triple with each channel in 0..1 (linear or sRGB depending on the operation).
type SpeechErrorKind — denied means the user or the browser refused the microphone — worth surfacing.
type StringValues — "An object whose values are all strings" — the constraint the dictionary type parameter
type TextLanguage — Coarse language bucket: Chinese / English / other only
type TranslateParams
type TruncatePosition — Which end of the string gets dropped when it is too long.

常量

const ADOPTED_SHEET_MARKER: "data-adopted-sheet"
const ADOPTED_STYLE_MARKER: "data-adopted-style" — Default marker attribute on the <style> fallback, identifying styles this module injected
const BRIDGE_MARKER: "__ranuts_bridge__"
const bridgeManager: BridgeManager
const circ: SpeedType
const Client: { connect: ({ id, targetWindow, targetOrigin, channel, }: BridgeManagerOptions) => { bridge: PostMessageBridge; id: string; }; remove: (id: strin…
const cubic: SpeedType
const DEFAULT_CHANNEL: "default"
const expo: SpeedType
const FMT: Record<string, string[]>
const HEX_COLOR_REGEX: RegExp — #rgb / #rrggbb (the # is required)
const isClient: boolean — Whether a window existed when this module was first imported.
const MessageCodec: { encode(data: any): string; decode<T = any>(encodedStr: string): T | null; encodeFile(file: File): Promise<string>; decodeFile(encoded: st… — Message codec.
const MimeType: Map<string, string>
const MOBILE_MEDIA_QUERY: "(max-width: 768px)" — Viewport breakpoint, matching where the mobile layout takes over
const Platform: { init: <T = unknown, R = unknown>(events: Record<string, MessageHandler<T, R>>) => { destroy: () => void; }; }
const quad: SpeedType
const quart: SpeedType
const quint: SpeedType
const RGB_REGEX: RegExp — rgb(r,g,b), no spaces — strip whitespace before matching
const RGBA_REGEX: RegExp — rgba(r,g,b,a), no spaces — strip whitespace before matching
const sine: SpeedType
const status: { message: Map<number, string>; code: Map<string, number>; codes: number[]; redirect: { 300: boolean; 301: boolean; 302: boolean; 303: boolean; 3…
const subscribers: SyncHook — Global event bus: a signal carrying a subscriber broadcasts through it on change
const UNAMBIGUOUS_ALPHABET: "ABCDEFGHJKLMNPQRSTUVWXYZ23456789" — Unambiguous by design: no 0/O, no 1/l/I. For codes a human reads aloud or retypes.
const ZIP_DEFLATE: 8
const ZIP_STORED: 0 — Compression methods this module understands.

`ranuts/sw`

Service Worker 缓存策略与预缓存协议 · 运行环境：仅 service worker · 源码：src/sw/index.ts

import { /* … */ } from 'ranuts/sw';

函数

cacheFirst(request: Request, options: CacheStrategyOptions) => Promise<Response> — Cache-first: serve the stored copy when there is one, otherwise fetch and
dropCachesExcept(keep: readonly string[], options?: { scope?: SWScope; }) => Promise<string[]> — Delete every cache except the ones named. Call it on activate so a new
networkFirst(request: Request, options: CacheStrategyOptions) => Promise<Response> — Network-first: go to the network, store what comes back, and fall back to the
precache(cacheName: string, urls: readonly string[], options?: { scope?: SWScope; }) => Promise<void> — Fill a cache with a list of URLs, skipping what is already there. Failures are
servePrecache(options: ServePrecacheOptions) => (() => void) — Answer the precache messages that prefetchUrls({ serviceWorkerMessage })

接口

interface CacheStrategyOptions
interface PrecacheMessageEvent — The bit of ExtendableMessageEvent used here, declared locally rather than pulled from
interface ServePrecacheOptions
interface SWScope — Minimal view of the SW global the helpers touch, so they can be unit-tested with a stub.

`ranuts/node`

Node 服务端工具（fs / http / ws / 中间件） · 运行环境：仅 node · 源码：src/node/index.ts

import { /* … */ } from 'ranuts/node';

函数

appendFile(path: string, content: string) => Promise<Ranuts.Identification> — Append content to an existing file
bodyMiddleware(options?: Partial<ServerBody>) => MiddlewareFunction
connect(connectMiddleware: ConnectMiddleware) => MiddlewareFunction
get({ url }: Request) => Promise<Response>
getIPAdress() => string | undefined
default(req: Req) => ParseUrl | undefined — Parse an IncomingMessage's request URL; the return type is always ParseUrl
prompt({ message, stream, defaultResponse }: PromptOption) => Promise<boolean>
queryFileInfo(path: string) => Promise<Ranuts.Identification> — Stat a file — typically to tell a file from a directory via data.isDirectory()
readDir(options: Options) => Array<string>
readFile(path: string, format?: BufferEncoding) => FilePromiseResult — Read a file, returning a status code and the content on success
readStream(option: ReadOption) => ReadStream
runCommand(command: string, args: string[]) => Promise<void>
startTask() => symbol
staticMiddleware(option?: Partial<Option>) => MiddlewareFunction
taskEnd(symbol: symbol) => number | bigint
traverse(dir: string, callback: Caller, pre?: string) => Promise<any> — Walk every directory recursively, running a function for each file found
traverseSync(dir: string, callback: Caller, pre?: string) => void — Synchronous: walk every directory recursively, running a function for each file found
watchFile(path: string, interval?: number) => Promise<Ranuts.Identification> — Watch a file for changes and report its status
writeFile(path: string, content: string) => Promise<Ranuts.Identification> — Write a file at the given path, truncating it if it exists and creating it if it does not
writeStream(option: WriteOption) => WriteStream
WSS(this: any, server: http.Server) => void — Create a WebSocket Server

类

class Router
class Server

接口

interface Context

常量

const isColorSupported: boolean

其他

default

`ranuts/visual`

2D 渲染引擎（Canvas / WebGL / WebGPU） · 运行环境：仅浏览器 · 源码：src/utils/visual/index.ts

import { /* … */ } from 'ranuts/visual';

类

class Application
class ColorAdjustFilter — A ready-made colour-grade filter: brightness, contrast and saturation. Mirrors the
class Container
class Filter — A full-screen post-processing pass. Sample the previous pass through u_texture (and
class Graphics
class WebGLRenderTarget

接口

interface ColorAdjustOptions
interface IApplicationOptions
interface IFillStyleOptions
interface ILineStyleOptions

枚举

enum LINE_CAP
enum LINE_JOIN
enum RENDERER_TYPE
enum SHAPE_TYPE

常量

const BYTES_PER_VERTEX: 12
const MAX_VERTEX_COUNT: 65536

`ranuts/i18n`

框架无关的 i18n 引擎（也从 ranuts/utils 再导出） · 运行环境：浏览器 + node · 源码：src/utils/i18n.ts

import { /* … */ } from 'ranuts/i18n';

函数

createI18n<TDict extends StringValues<TDict> = MessageDict>(config?: I18nConfig<TDict>) => I18nCore<TDict> — Create and register the global i18n singleton.
useI18n<TDict extends StringValues<TDict> = MessageDict>() => I18nCore<TDict> | null — The active global instance, or null when none was created. Pass the same

类

class I18nCore — The engine. Optionally parameterised by your dictionary shape.

接口

interface I18nConfig

类型

type LocaleChangeHandler
type LocaleMessages — Locale → dictionary. Parameterised by the dictionary shape so an app can hand in its own
type MessageDict
type StringValues — "An object whose values are all strings" — the constraint the dictionary type parameter
type TranslateParams

`ranuts/vnode`

Snabbdom 风格的虚拟 DOM · 运行环境：浏览器 · 源码：src/vnode/index.ts

import { /* … */ } from 'ranuts/vnode';

函数

addNS(data: VNodeData, children: Array<VNode | string | number> | undefined, sel: string | undefined) => void
create(tagName: string, options?: ElementCreationOptions) => Chain
h{ (sel: string): VNode; (sel: string, data: VNodeData | null): VNode; (sel: string, children: VNodeChildren): VNode; (sel: string, data: VNodeData | null, chi… (+3 overloads)
init() => (oldVnode: VNode | Element, vnode: VNode) => VNode
vnode(sel: string | undefined, data: any | undefined, children: Array<VNode | string | number> | undefined, text: string | number | undefined, elm: Element | T…

类

class Chain — Chainable DOM operations

接口

interface DOMAPI
interface Fragment
interface Hooks
interface VNode
interface VNodeData

类型

type ArrayOrElement
type Key
type ModuleHook
type Modules
type VNodeChildElement
type VNodeChildren
type VNodes

常量

const attributesModule: { create: (oldVnode: VNode, vnode: VNode) => void; update: (oldVnode: VNode, vnode: VNode) => void; }
const classModule: { create: (oldVnode: VNode, vnode: VNode) => void; update: (oldVnode: VNode, vnode: VNode) => void; }
const eventListenersModule: { create: (oldVnode: VNode, vnode?: VNode) => void; update: (oldVnode: VNode, vnode?: VNode) => void; destroy: (oldVnode: VNode, vn…
const htmlDomApi: DOMAPI
const modules: Modules
const propsModule: { create: (oldVnode: VNode, vnode: VNode) => void; update: (oldVnode: VNode, vnode: VNode) => void; }
const styleModule: { pre: () => void; create: (oldVnode: VNode, vnode: VNode) => void; update: (oldVnode: VNode, vnode: VNode) => void; destroy: (vnode: VNode)…

命名空间

namespace is — Type guards — array / string / primitive / VNode

ranuts API（自动生成） ​

入口点 ​

ranuts/utils ​

函数 ​

类 ​

接口 ​

类型 ​

常量 ​

ranuts/sw ​

函数 ​

接口 ​

ranuts/node ​

函数 ​

类 ​

接口 ​

常量 ​

其他 ​

ranuts/visual ​

类 ​

接口 ​

枚举 ​

常量 ​

ranuts/i18n ​

函数 ​

类 ​

接口 ​

类型 ​

ranuts/vnode ​

函数 ​

类 ​

接口 ​

类型 ​

常量 ​

命名空间 ​

ranuts API（自动生成）

入口点

`ranuts/utils`

函数

类

接口

类型

常量

`ranuts/sw`

函数

接口

`ranuts/node`

函数

类

接口

常量

其他

`ranuts/visual`

类

接口

枚举

常量

`ranuts/i18n`

函数

类

接口

类型

`ranuts/vnode`

函数

类

接口

类型

常量

命名空间