@biorate/tools

Collection of low‑level JavaScript/TypeScript utilities used across the @biorate monorepo.

Features

• define — Object.defineProperty shorthand with cwe modifier strings.
• object — accessor detection, prototype walking, key sorting.
• path — file path utilities built on Node path module.
• env — runtime environment detection (isServer, globalThis polyfill).
• timer — promise-wrapped setTimeout, process.nextTick, setImmediate.
• time — process.hrtime-based diff and unit conversion.
• events — promisified .once() for EventEmitter.
• buffer — UInt29 variable-length integer encode/decode (AMF protocol).
• stream — load a readable stream into a Buffer.
• import — CJS‑to‑ESM default export unwrapping.
• errors — typed error classes: UInt29OutOfBoundsError, TimeIncorrectFormatError.

Installation

pnpm add @biorate/tools

Module reference

env — Runtime environment

import { env } from '@biorate/tools';

| Export | Type | Description | |--------------|-----------|-----------------------------------------------------------------------------| | globalThis | any | Polyfill — resolved via Function('return this')(). | | isServer | boolean | true if globalThis.window !== globalThis (i.e. not a browser). |

Example:

import { env } from '@biorate/tools';

if (env.isServer) {
  console.log('Running on Node.js');
}

define — Property / accessor definition

import { define } from '@biorate/tools';

Shorthand for Object.defineProperty. Both prop and accessor accept a cwe modifier string:

| Char | Flag | |------|----------------| | c | configurable | | w | writable | | e | enumerable |

define.prop(context, field?, value?, mods?)

Returns a chainable function when partially applied.

const obj = {};

define.prop(obj, 'a', 1, 'cwe')  // configurable + writable + enumerable
       ('b', 2, 'c')             // configurable only
       ('c', 3, '');             // none

console.log(obj); // { a: 1 }

Object.getOwnPropertyDescriptor(obj, 'a');
// { value: 1, writable: true, enumerable: true, configurable: true }

Object.getOwnPropertyDescriptor(obj, 'b');
// { value: 2, writable: false, enumerable: false, configurable: true }

Object.getOwnPropertyDescriptor(obj, 'c');
// { value: 3, writable: false, enumerable: false, configurable: false }

define.accessor(context, field?, accessor?, mods?)

Same curried pattern for getters/setters.

const obj = { _value: 0 };

define.accessor(obj, 'value', {
  get() { return this._value; },
  set(v: number) { this._value = v; },
}, 'cw');

Object.getOwnPropertyDescriptor(obj, 'value');
// { get: [Function], set: [Function], enumerable: false, configurable: true }

object — Object helpers

import { object } from '@biorate/tools';

object.isAccessor(obj, field): boolean

Checks if a property is defined via getter/setter.

const obj = { get x() { return 1; } };
console.log(object.isAccessor(obj, 'x')); // true
console.log(object.isAccessor(obj, 'y')); // false

object.walkProto(obj, callback?)

Walks the prototype chain, invoking callback for each prototype (stops before Object).

class A {}
class B extends A {}
class C extends B {}

object.walkProto(new C(), console.log);
// B {}
// A {}

object.kSort(obj): Record<string, unknown>

Returns a new object with keys sorted alphabetically.

console.log(object.kSort({ b: 1, a: 2, d: 3, c: 4 }));
// { a: 2, b: 1, c: 3, d: 4 }

path — File path utilities

import { path } from '@biorate/tools';

| Function | Signature | Description | |-------------|----------------------------------|------------------------------------------------| | dirname | (filepath, full?) | Last directory component (full=true → full path). | | basename | (filepath, ext?) | File name, strips .js by default. | | extname | (filepath) | File extension (e.g. .html). | | create | (...args) | path.join + normalize. |

console.log(path.dirname('/www/root/index.html'));        // root
console.log(path.dirname('/www/root/index.html', true));  // /www/root
console.log(path.basename('/www/root/index.js'));         // index
console.log(path.basename('/www/root/index.html'));       // index.html  (no .html to strip)
console.log(path.basename('/www/root/index.html', '.html')); // index
console.log(path.extname('/www/root/index.html'));        // .html
console.log(path.create('www', 'root/a/b/', '/c/', '', '/index.js'));
// www/root/a/b/c/index.js

timer — Promise-based delays

import { timer } from '@biorate/tools';

| Export | Signature | Description | |-------------|-----------------------|----------------------------------------------| | wait | (timeout?) | Resolves after timeout ms (setTimeout). | | tick | () | Resolves on next tick (process.nextTick). | | immediate | () | Resolves via setImmediate. |

await timer.wait(1000);   // wait 1 second
await timer.tick();       // yield to next tick
await timer.immediate();  // yield to check phase

time — Elapsed time & unit conversion

import { time } from '@biorate/tools';

time.diff(): () => number

Returns a closure that captures process.hrtime() start. Each call returns elapsed milliseconds (microsecond precision).

const elapsed = time.diff();
// ... do work ...
console.log(elapsed()); // e.g. 12.345
console.log(elapsed()); // cumulative, growing

time.msTo(ms, format?, digits?): number

Converts milliseconds to another unit. Round if digits >= 0.

| Format | Unit | |--------|--------------| | 'µs' | Microseconds | | 'ms' | Milliseconds | | 's' | Seconds | | 'm' | Minutes | | 'h' | Hours | | 'd' | Days |

console.log(time.msTo(1500, 's'));       // 1.5
console.log(time.msTo(86400000, 'd'));   // 1
console.log(time.msTo(1234, 's', 2));    // 1.23

Throws TimeIncorrectFormatError on unknown format.

events — EventEmitter promisified

import { events } from '@biorate/tools';

events.once(object, event): Promise<unknown[]>

Returns a Promise that resolves with the event arguments the next time event is emitted.

import { EventEmitter } from 'events';
import { events } from '@biorate/tools';

const emitter = new EventEmitter();
const promise = events.once(emitter, 'data');
emitter.emit('data', 1, 2, 3);
const args = await promise;
console.log(args); // [1, 2, 3]

Accepts any object with on / once signature (IEventLike).

buffer — UInt29 variable-length integer encoding

import { buffer } from '@biorate/tools';

Implements the AMF0/AMF3 UInt29 wire format (used in Adobe Flash protocols).

| Export | Type | Description | |------------------------|--------------|---------------------------------------------------| | MAX_UINT29 | 536870911 | (1 << 29) - 1 | | MIN_UINT29 | 0 | Minimum value. | | writeUInt29 | (buf, val, offset?) => number | Encodes val at offset, returns new offset. | | readUInt29 | (buf, offset?) => number | Decodes value from offset. | | uInt29BytesLength | (val) => number | Bytes needed to encode (1–4). |

Encoding produces 1–4 bytes depending on value range:

| Range | Bytes | |-------------------|-------| | 0–0x7F | 1 | | 0x80–0x3FFF | 2 | | 0x4000–0x1FFFFF | 3 | | 0x200000–0x1FFFFFFF | 4 |

Throws UInt29OutOfBoundsError if value is outside [0, 536870911].

import { buffer } from '@biorate/tools';

const buf = Buffer.alloc(4);
const end = buffer.writeUInt29(buf, 300);
console.log(end);        // 2
console.log(buf);        // <82 ac>  (two bytes)

const val = buffer.readUInt29(buf);
console.log(val);        // 300

console.log(buffer.uInt29BytesLength(300));   // 2
console.log(buffer.uInt29BytesLength(0x7F));  // 1
console.log(buffer.uInt29BytesLength(536870911)); // 4

stream — Stream to Buffer

import { stream } from '@biorate/tools';

stream.load(readable): Promise<Buffer>

Reads all data from a readable stream into a single Buffer. Listens to data, error, and end events.

import { createReadStream } from 'fs';
import { stream } from '@biorate/tools';

const data = await stream.load(createReadStream('/path/to/file'));
console.log(data.length);

import — CJS default-export unwrapping

import { unwrapCjsDefaultExport } from '@biorate/tools';

unwrapCjsDefaultExport<T>(mod, moduleLabel?, maxDepth?): T

Recursively unwraps { default: ... } wrappers produced when ESM import consumes a CJS module with __esModule + exports.default (common in packages like inversify-inject-decorators).

const getDecorators = unwrapCjsDefaultExport(importedModule, 'my-pkg');

Throws TypeError if a function is not resolved within maxDepth iterations (default 4).

errors — Typed error classes

import { UInt29OutOfBoundsError, TimeIncorrectFormatError } from '@biorate/tools';

| Error | Thrown by | Message | |-----------------------------|----------------------------------|---------------------------------------------------| | UInt29OutOfBoundsError | buffer.writeUInt29, uInt29BytesLength | UInt29 value is out of bounds [0], shoud be >= [0], and <= [536870911] | | TimeIncorrectFormatError | time.msTo | Time incorrect format: [xyz] |

Both extend BaseError from @biorate/errors.

Module index

| Export | Source | Description | |-----------------|---------------|-----------------------------------------| | Flat | | | | unwrapCjsDefaultExport | import.ts | CJS default‑export unwrapping. | | UInt29OutOfBoundsError | errors.ts | Buffer range error. | | TimeIncorrectFormatError | errors.ts | Time format error. | | IDefine | interfaces.ts | Mods union & Accessor descriptor. | | IEventLike | interfaces.ts | EventEmitter duck-type. | | Namespaced | | | | env | env.ts | globalThis, isServer. | | define | define.ts | prop, accessor. | | object | object.ts | isAccessor, walkProto, kSort. | | path | path.ts | dirname, basename, extname, create. | | timer | timer.ts | wait, tick, immediate. | | time | time.ts | diff, msTo. | | events | events.ts | once. | | buffer | buffer.ts | MAX_UINT29, MIN_UINT29, writeUInt29, readUInt29, uInt29BytesLength. | | stream | stream.ts | load. |

Architecture

@biorate/tools
│
├── env                          Runtime detection
│   ├── globalThis               globalThis polyfill
│   └── isServer                 Server vs browser
│
├── define                       Object.defineProperty shorthand
│   ├── prop                     Data property (cwe string)
│   └── accessor                 Getter/setter (ce string)
│
├── object                       Object introspection
│   ├── isAccessor               Getter/setter check
│   ├── walkProto                Prototype chain walk
│   └── kSort                    Key-sorted clone
│
├── path                         File path utilities
│   ├── dirname                  Short/full directory
│   ├── basename                 Name without ext
│   ├── extname                  Extension
│   └── create                   Normalised join
│
├── timer                        Promise-based scheduling
│   ├── wait                     setTimeout wrapper
│   ├── tick                     nextTick wrapper
│   └── immediate                setImmediate wrapper
│
├── time                         High-res timing
│   ├── diff                     hrtime closure
│   └── msTo                     Unit conversion
│
├── events                       EventEmitter helpers
│   └── once                     Promisified .once()
│
├── buffer                       UInt29 (variable-length int)
│   ├── MAX_UINT29               Max value (2^29 - 1)
│   ├── MIN_UINT29               Min value (0)
│   ├── writeUInt29              Encode to buffer
│   ├── readUInt29               Decode from buffer
│   └── uInt29BytesLength        Bytes needed for encode
│
├── stream                       Stream utilities
│   └── load                     Stream → Buffer
│
├── import                       CJS/ESM interop
│   └── unwrapCjsDefaultExport   Recursive default unwrap
│
└── errors                       Error classes
    ├── UInt29OutOfBoundsError
    └── TimeIncorrectFormatError

Learn

• Documentation can be found here - docs.

Release History

See the CHANGELOG

License

MIT

Copyright (c) 2021-present Leonid Levkin (llevkin)