Utilities
此内容尚不支持你的语言。
The framework solves a handful of problems for itself that turn up again in the
code you write on top of it: representing “there might be no value” without
null, carrying a failure without throwing, computing something once on first
use, draining a queue that keeps growing, looking a pair up from either end,
naming something unguessably, printing a value on a path where throwing would
replace the error you were reporting, and depending on a package you do not
want to make mandatory.
These are the answers it already uses. The ones you meet while using the
framework itself are exported from the root entry point, and everything below
imports from 'actor-ts' for that reason; the whole directory — including the
pieces the root does not carry — is on the actor-ts/util subpath
(The whole toolbox, below). None of them
are required to use actor-ts — reach for one when you have the problem it
solves.
import { BidirectionalMap, BidirectionalMultiMap, Lazy, RingBuffer, none, safeStringify, some, tryOf,} from 'actor-ts';Option — a value that might not be there
Section titled “Option — a value that might not be there”Option<T> is Some<T> | None. Prefer it over T | null in domain-API
returns and long-lived fields: the type forces the empty case to be handled at
the point of use rather than remembered.
import { fromNullable, none, some, type Option } from 'actor-ts';
const leader: Option<string> = some('node-a');leader.map((address) => address.toUpperCase()).getOrElse('<none>'); // 'NODE-A'none.getOrElse('<none>'); // '<none>'
fromNullable(process.env.SEED_NODE); // Some | None, from a nullable| Export | What it does |
|---|---|
some(value) / none | Build one. none is a shared instance, not a factory. |
fromNullable(value) | null / undefined → None, anything else → Some. |
fromPredicate(value, pred) | Some when the predicate holds, else None. |
firstSome(...options) | The first Some, or None. |
The API mirrors Scala’s where practical: map, flatMap, filter,
filterNot, fold, getOrElse, orElse, exists, forall, contains,
forEach, toArray, toNullable, isSome, isNone. isSome() and
isNone() are type guards, and both classes work with ts-pattern’s
P.instanceOf(Some).
Nullable is still the right choice in three places, and the framework uses it
there on purpose: hot-path internal fields where the wrapper would show up in a
profile, serialization boundaries that have to round-trip through null, and
optional parameters with ergonomic defaults.
Try — a computation that may have thrown
Section titled “Try — a computation that may have thrown”Try<T> is Success<T> | Failure. It turns a throw into a value you can pass
around, which is what you want when the failure has to travel — into a message,
across an ask, into a state machine.
import { tryOf } from 'actor-ts';
const parsed = tryOf(() => JSON.parse(payload));
parsed .map((body) => body.userId) .recover(() => 'anonymous') .getOrElse('anonymous');tryOf(compute) runs the function and captures whatever it throws;
success(value) and failure(error) build one directly. Beyond the shared
map / flatMap / fold / getOrElse / orElse / filter / forEach,
Try adds recover (map the error to a value), recoverWith (map it to
another Try), get (rethrow), toNullable and toError.
trySequence(tries) turns an array of Try<T> into a Try<T[]> that fails on
the first failure.
Either — two outcomes, neither of them an error
Section titled “Either — two outcomes, neither of them an error”Either<L, R> is Left<L> | Right<R>, right-biased: map and flatMap work
on the right. Reach for it over Try when the failure side is a domain value
you want typed — a validation report, a rejection reason — rather than a thrown
error.
import { left, right, type Either } from 'actor-ts';
function parseAge(raw: string): Either<string, number> { const value = Number(raw); return Number.isInteger(value) && value >= 0 ? right(value) : left(`not an age: ${raw}`);}
parseAge('42').fold((reason) => `rejected: ${reason}`, (age) => `age ${age}`);mapLeft, bimap and swap work the other side; isLeft() and isRight()
are type guards. eitherOf(compute) catches a throw into Left<Error>, and
eitherSequence collects an array the way trySequence does.
Lazy — compute once, on first use
Section titled “Lazy — compute once, on first use”Lazy<T> is Scala’s lazy val: the computation runs on the first get() and
the result is memoised, including a thrown failure, so an expensive or
side-effecting setup happens exactly once no matter how many callers ask.
import { Lazy, lazyImportModule } from 'actor-ts';
const redisLazy = Lazy.of(() => lazyImportModule<typeof import('ioredis')>('ioredis'));
// First call imports; every later one returns the same promise.const redis = await redisLazy.get();Lazy.of(compute) (aliased as lazy) and Lazy.evaluated(value) build one.
get() forces it, peek() returns the value only if it has already been
computed, getSync() unwraps a resolved async cell, and map / flatMap /
forEach compose without forcing. reset() and setOverride(value) exist for
tests — they are the reason a lazily-imported backend can be swapped for a fake
without touching the production path.
RingBuffer — a queue that stays fast when it gets deep
Section titled “RingBuffer — a queue that stays fast when it gets deep”RingBuffer<T> is a first-in-first-out queue whose removal from the front is
O(1). It exists because Array.prototype.shift() is not: it reindexes every
element still queued, so the cost of taking one item grows with the number of
items behind it. That is invisible on a queue of ten and expensive on a queue
of a hundred thousand — which is what an actor’s mailbox becomes when it falls
behind its producers, since the default mailbox has no ceiling.
import { RingBuffer } from 'actor-ts';
const pending = new RingBuffer<string>();pending.push('a');pending.push('b');pending.shift(); // 'a'pending.unshiftAll(['x', 'y']); // both go in front of 'b', in this orderpending.length; // 3pending.drain(); // ['x', 'y', 'b'] — and the ring is emptyFour operations and nothing else. push appends (amortised O(1) — the
backing array doubles, and is not allocated at all until the first push, so an
unused ring costs what an empty [] costs). shift takes the front. drain
empties it into a fresh array and releases the backing store, so a queue that
grew to a million gives the memory back. unshiftAll(items) puts a whole batch
in front in one move, without a spread — the framework uses it to replay a
stash of up to a thousand messages, where unshift(...items) would both
reindex the queue once per message and push the batch onto the call stack as
arguments.
It is not a general-purpose deque, deliberately: every extra operation is
another index-wrapping edge case in a type that sits on the message path of
every actor in the system. Both queues inside a
Mailbox are one, and so is the
ThroughputDispatcher work queue.
BidirectionalMap — a map with a maintained inverse
Section titled “BidirectionalMap — a map with a maintained inverse”BidirectionalMap<K, V> is a Map<K, V> that also answers value → key. It
exists because a reverse index written by hand is two maps that have to be
updated in lockstep, and the failure mode when they drift is silent: a stale
entry keeps answering for a pair that is already gone.
import { BidirectionalMap } from 'actor-ts';
const seats = new BidirectionalMap<string, number>();seats.set('ada', 1);seats.set('grace', 2);
seats.get('ada'); // 1seats.getKey(2); // 'grace' ← the direction a Map cannot answerseats.deleteValue(1); // removes the pair from both sidesIt implements Map<K, V> in full, so it drops into anything that takes one —
new Map(bidirectionalMap), spreading, for…of, forEach.
Beyond Map | What it does |
|---|---|
getKey(value) / hasValue(value) / deleteValue(value) | The reverse direction. |
trySet(key, value) | Binds only if that removes nothing; false otherwise. |
inverse() | The same map read the other way round — a view, not a copy. |
reverseEntries() | [value, key] pairs. |
getOrInsertKey(value, defaultKey) | Like getOrInsert, from the value side; returns a key. |
getOrInsertComputedKey(value, callback) | The same, minting the key on demand. callback runs at most once. |
keySize / valueSize | Distinct keys and distinct values. Both always equal size, because the relation is 1:1 — they exist so this type and BidirectionalMultiMap, where the counts genuinely differ, read alike. |
Both directions are backed by Map, so both compare by SameValueZero:
NaN works as a key and as a value, 0 and -0 are the same, and two
structurally equal objects are two different values. When you need structural
identity, index a derived string — that is what the framework’s own shard does,
keying on ref.path.toString() rather than on the ref.
It can live in persistent state
Section titled “It can live in persistent state”Unlike an ordinary class, a BidirectionalMap survives a journal, snapshot or
durable-state round-trip as a real instance — no
event adapter, no serializer registration,
nothing at the boundary. The tagged JSON tree knows it the way it knows Map
and Set.
type State = { seats: BidirectionalMap<string, number> };
class SeatingPlan extends PersistentActor<Command, Event, State> { initialState(): State { return { seats: new BidirectionalMap() }; } // After a restart, state.seats is a BidirectionalMap again — and // state.seats.getKey(2) works, even though only the forward pairs // were ever written.}Only the forward pairs go to disk; the inverse is rebuilt on decode. See what events and state may contain for the full round-trip table.
A store configured with withSerializer(new CborSerializer()) carries it too,
under CBOR tag 27. That was not always so — until
#1036 the CBOR codec
dropped it, along with Map and Set, without raising anything.
BidirectionalMultiMap — the same for a many-to-many relation
Section titled “BidirectionalMultiMap — the same for a many-to-many relation”BidirectionalMultiMap<L, R> relates many lefts to many rights and answers in
both directions. It exists for the shape a subscription registry has: one
subscriber holds many topics, one topic has many subscribers, and the message
telling you a subscriber is gone carries only the subscriber.
import { BidirectionalMultiMap } from 'actor-ts';
const subscriptions = new BidirectionalMultiMap<string, string>();subscriptions.add('news', 'ada');subscriptions.add('news', 'grace');subscriptions.add('sport', 'ada');
subscriptions.get('news'); // Set { 'ada', 'grace' }subscriptions.getKeys('ada'); // Set { 'news', 'sport' } ← the reverse directionsubscriptions.size; // 3 — pairs, not participantssubscriptions.leftSize; // 2 — distinct topicssubscriptions.rightSize; // 2 — distinct subscribers
subscriptions.deleteRight('ada'); // ada leaves every topic at oncesubscriptions.hasLeft('sport'); // false — sport held only ada, so it is gone tooThat last line is the invariant worth knowing: there is no such thing as an
empty participant. Removing the last partner removes the participant from
both directions. A topic left behind holding an empty subscriber set is
invisible to a pair count, keeps occupying whatever cap bounds your topics, and
would let inverse() hand back something related to nothing.
| Beyond a pair of maps | What it does |
|---|---|
add(left, right) / delete(left, right) | One pair, both directions. add is idempotent. |
get(left) / getKeys(right) | Everything one side is related to. Empty set when absent — never undefined, so you can iterate without a guard. |
deleteLeft(left) / deleteRight(right) | Drop one participant entirely — the Terminated case. |
hasLeft(left) / hasRight(right) | Whether that participant has at least one partner. |
lefts() / rights() | The participants, each listed once. |
size / leftSize / rightSize | Pairs, distinct lefts, distinct rights. All three O(1) — reach for one of the participant counts rather than measuring [...lefts()]. |
inverse() | The relation read the other way round — a view, not a copy. size stays true on both. |
Equality is SameValueZero, as with BidirectionalMap, and for the same
reason: both directions are backed by Map and Set. Two structurally equal
objects are two different participants, so index a derived string when you need
structural identity — which is what the framework’s own call sites do, keying
subscribers on ref.path.toString() rather than on the ref. A Terminated
carries the cell’s own self ref, which need not be the object that
subscribed; the path is the identity both sides agree on.
It can live in persistent state too
Section titled “It can live in persistent state too”Like its 1:1 sibling, it survives a journal, snapshot or durable-state round-trip as a real instance — no adapter, no registration. Only the forward direction is written, as an adjacency list; the inverse is rebuilt on decode, so the two halves cannot come back disagreeing. The same CBOR caveat applies.
Random strings and identifiers
Section titled “Random strings and identifiers”| Export | What it does |
|---|---|
randomString(length, options?, exists?) | length characters from the enabled classes. Default: alphanumeric. exists may take the second slot when you pass no options. |
randomHex(length, exists?) | length lowercase hex characters — for wire formats that mandate [0-9a-f]. |
randomId(length, exists?) | length characters for something you have to name yourself. |
randomUuid(exists?) | A version-4 UUID — for an identifier that must not collide with one minted elsewhere. |
RandomStringOptions | { lowerCase?, upperCase?, digits? } — each defaults to true. |
ExistsPredicate | (candidate: string) => boolean — the optional collision check all four take. true means “taken, draw again”. |
The first three draw from globalThis.crypto, correct the modulo bias that a
plain byte % alphabet.length introduces, and return exactly the length you
asked for — never fewer. randomUuid delegates to
globalThis.crypto.randomUUID().
import { randomId, randomString, randomUuid } from 'actor-ts';
const sessionId = randomId(12); // '9f3c1ab0e7d2'const coupon = randomString(8, { lowerCase: false, digits: true }); // 'K7Q2XP4M'const persistenceId = randomUuid(); // 'f81d4fae-7dec-41d0-a765-00a0c91e6bf6'randomId is the one to reach for when naming an actor. An actor name ends up
in an actor path, and a path is an address: on the cluster wire, anything that
can render one can send to it. A counter makes that address guessable — knowing
one hands you the next — which is why the framework names anonymous actors and
ask reply refs from here rather than from $1, $2, $3.
randomHex exists separately because some alphabets are not a style choice.
W3C trace-context mandates [0-9a-f]{32} and [0-9a-f]{16} for a
traceparent header, and a peer rejects anything else.
randomUuid sits at the other end of the entropy scale from randomId, and the
split between the two is worth getting right. randomId(12) is ~48 bits: unguessable among
the names one process holds live at once, which is the only uniqueness an actor
name has to carry. randomUuid() is 122 random bits, which is what it takes for
an identifier to stay distinct from one minted in another process, on another
machine, years later, with nothing coordinating them — a PersistenceId for a
new aggregate, a correlation id crossing a broker, a key another system will
read.
Drawing until you get a free one
Section titled “Drawing until you get a free one”All four take an optional predicate as their last argument and draw again while
it answers true:
import { randomUuid } from 'actor-ts';
const userId = randomUuid((id) => state.users.has(id));which is the loop that used to sit at the call site:
let userId: UserId;do { userId = randomUuid();} while (state.users.has(userId));The callback is that while condition. That is why it is named exists and
why true means “draw again” — an accept-predicate would read as the negation
of the loop it replaces, and would put a ! on every Map- or Set-backed
call site. randomString takes it in the second slot when you pass no options
and in the third when you do: randomString(8, exists),
randomString(8, { digits: false }, exists).
It reads, it does not write. Nothing records the accepted value for you, so
whatever exists consults is still yours to update.
Stringifying a value that already went wrong
Section titled “Stringifying a value that already went wrong”safeStringify(value, maxLength?) renders any value as a string and never
throws.
import { Actor, safeStringify } from 'actor-ts';
class Worker extends Actor<unknown> { onReceive(message: unknown) { this.log.warn(`unhandled message: ${safeStringify(message)}`); }}JSON.stringify throws on a circular structure and on a BigInt. Using it to
build a log line or an error message therefore risks replacing the problem you
were reporting with a different one — thrown from inside the reporting code,
where a caller is least likely to be handling it. An onReceive that logs a
message it did not expect is exactly that situation: the message is
unrecognised, so nothing is known about its shape.
Cycles collapse to [Circular], BigInt renders with an n suffix, functions
and symbols are named, and the result is capped (8 KiB by default) rather than
allowed to grow into a multi-megabyte string that blocks the event loop while
being built.
Logging a URL without logging the password
Section titled “Logging a URL without logging the password”A connection URL is the one string in a configuration that routinely carries a
secret inline — amqp://user:pass@host/vhost, mongodb+srv://user:pass@cluster
— and the places that print one are the places least likely to be reviewed for
disclosure: a rejection message, a reconnect warning, a frame a remote peer
sent. Two renderings, for two different jobs.
import { redactUrlCredentials, redactedUrlLabel } from 'actor-ts';
redactUrlCredentials('amqp://user:pass@rabbit:5672/vhost');// → 'amqp://***@rabbit:5672/vhost'
redactedUrlLabel('wss://user:pass@example.com/ws/orders?token=abc');// → 'wss://example.com/ws/orders'redactUrlCredentials(value) masks the userinfo and changes nothing else —
no normalisation, no trailing slash, no lowercased host — so an operator still
recognises the value they typed. It is a strict no-op on anything without a
scheme://…@ authority, which is what makes it safe to apply unconditionally to
a value that only might be a URL (':memory:', 'file:local.db',
'not a url' all come back verbatim). This is what the framework’s own
option validation puts into every OptionsError
that rejects a URL. A password with an unescaped /, ? or # in it is
masked too, by this function and by both below — RFC 3986 wants all three
percent-encoded, but a pasted password carries them as they are, so the
userinfo runs to the last @ before the next ://. The price is paid by an
@ further on in a path or a query, which reads the same way:
https://host/a@b comes back as https://***@b — the *** says that what
follows it is what followed the last @, not necessarily the host. The
userinfo stays on its own line: once an @ has been seen, a line break ends
it, and before the first @ the scan goes on past a line break only up to the
first space or tab. So the next frame of a stack trace — every frame of a
scoped package carries an @ — or the next line of a log is never taken for a
password, while a secret read from a file is still masked whole: a line break
that an @ follows, such as a trailing newline in front of the @, is part
of the userinfo, and so is a secret wrapped over several lines. The rule gives
up two shapes of secret, and neither is masked whole. A space or a tab after a
line break ends the scan before it reaches the @, so
'amqp://user:pa\n ss@rabbit' comes back unchanged, and an @ in front of a
line break ends the userinfo there, so 'amqp://user:p@ss\nword@rabbit' comes
back as 'amqp://***@ss\nword@rabbit', which keeps ss and word.
redactedUrlLabel hides both in a value it rebuilds from its parse — one URL,
with no , and no second :// in front of a ? or # — but not in every
value it masks instead: 'nats://a:b@h1,nats://u:pa\n ss@h2' comes back as
'nats://***@h1,nats://u:pa\n ss@h2'.
A URL the runtime has already parsed needs no such guess. For the one a
request went to, or a redirect target resolved against it,
redactParsedUrlCredentials(url) masks exactly its username and password
and keeps an @ that its path or query carries:
import { redactParsedUrlCredentials } from 'actor-ts';
redactParsedUrlCredentials(new URL('https://registry.npmjs.org/@types%2fnode'));// → 'https://registry.npmjs.org/@types%2fnode'
redactParsedUrlCredentials(new URL('https://user:pass@idp.example/authorize?login_hint=a@b'));// → 'https://***@idp.example/authorize?login_hint=a@b'What follows the host still goes through the scan above, so a URL written into
a path or a query (?target=http://user:pass@inner/) keeps its own credential
masked. The result is the URL’s href, normalised the way the runtime sends
it — which is why this is the rendering for a URL a request is made with, and
not for a value someone typed: a mistyped password with a / in it
(user:12/PW1@host) parses as a host, a port and a path, so parsing a
configured string only to render it would print the very password it was
meant to hide. HttpClient names the URLs in its redirect and size errors
this way, and SseActor the target of a redirect it refuses; a Location
that does not parse falls back to the scan.
redactedUrlLabel(value) goes further and reduces a URL to a stable identity:
scheme, host, port and path, with the userinfo and the query string dropped —
a WebSocket endpoint is commonly authenticated with a ?token=…. The path is
kept deliberately, since it is what tells two connections to the same host
apart. A value that is not one URL is masked instead of parsed: a scheme-less
user:password@host — the server form memjs and nats.js accept — comes back
as ***@host, and a comma-joined list keeps every entry, each with its
userinfo masked.
The label masks every userinfo the way the scan does — to the last @ before
the next :// — and, but for the two multi-line shapes above, shows no
credential that the v0.17.0 label kept out. Three cases follow, each held
against a copy of the released label:
- An
@past the host names no host.https://user:pass@hooks.example/notify?to=ops@example.comis a URL forhooks.examplewith an@in its query, and byte for byte also a password ending inopsfor the hostexample.com. No host is right for both readings, so the label names none and comes back ashttps://***. The same holds with no credential at all —wss://chat.example.com/rooms/@generalandhttps://host/a@bcome back aswss://***andhttps://***— and the label never shows what follows a?or#, so a query token with an@in it gives none of its tail away:wss://feed.example.com/ws?token=a@bcomes back aswss://***. Where WHATWG reads no valid host in front of the/, the scan’s reading is the only one and its host is named:amqp://user:pa/PW1@host:5672/vhostcomes back asamqp://host:5672/vhost. - A comma in a password is masked with it, wherever an
@stands:amqp://user:a,b@hostcomes back asamqp://host, andamqp://user:a@b,c@hostasamqp://***@host. A credentialed list whose entries do not each open with ascheme://is the same string as such a password, so the hosts in front of its last@go with the mask, and the***@stays to say so:nats://h1:4222,u:p@h2:4222comes back asnats://***@h2:4222. Give every entry its ownscheme://and every host stays:nats://u:p@a:4222,nats://u:p@b:4222comes back asnats://***@a:4222,nats://***@b:4222. - A scheme-less
user:a,b@hosthas nothing to say where its userinfo begins, and still comes back asuser:a,***@host.
Use it wherever a remote peer influences how often a line is
written — which is to say wherever the URL would otherwise be replayed into
the log at someone else’s discretion. The WebsocketClientActor uses it for its
oversize-frame warning. That line is no longer written per frame: the breach
closes the connection, so a peer gets one line per dial. The redaction stands
regardless, because a peer that provokes reconnects still decides how many
dials there are.
BrokerActor is the other consumer, and its case is not a log at all:
redactedEndpointLabel() is what reaches BrokerConnected,
BrokerDisconnected, BrokerReconnectFailed and BrokerReconnectAttempt,
which are published on the system-wide EventStream. That audience is wider
than a log file — subscribe has no authorization concept — and the events
fire on the happy path, once per connect and once per reconnect attempt. It
also shows the fallback doing real work: a joined server list is never handed
to the URL parser, so it takes the scan path and comes back as
nats://***@a:4222,nats://***@b:4222 rather than being flattened to one
host.
A third rendering exists for the case where the string is not yours to begin
with. redactErrorCredentials(error) applies the first one to an Error some
driver threw — several put the connection target, userinfo included, into the
message they raise — and returns a copy, because that error belongs to the
driver and may still be held or already handed to listeners of its own.
import { redactErrorCredentials } from 'actor-ts';
const safe = redactErrorCredentials(driverError);// message, stack, own string properties and the `cause` chain, all maskedThe copy is made to answer the questions a subscriber actually asks: it carries
the original’s prototype, so instanceof still holds, and its own enumerable
properties, so code / errno / syscall survive. What it deliberately does
not carry is anything reachable only through a getter — a getter can recompute
the secret, and a redaction that a property read can undo is not one. This is
what puts BrokerDisconnected.cause and BrokerReconnectFailed.cause on the
same footing as the endpoint beside them; without it an operator reading
“broker events no longer carry my password” would have been right about one
field and wrong about the event.
Optional peer dependencies
Section titled “Optional peer dependencies”lazyImportModule(name, options?) imports a module dynamically and, when it is
missing, throws an error that names the package and the command that installs
it.
import { Lazy, lazyImportModule } from 'actor-ts';
const redisLazy = Lazy.of(() => lazyImportModule<typeof import('ioredis')>('ioredis', { context: 'MyCacheActor' }),);
// MyCacheActor requires the 'ioredis' package. Install it with: npm install ioredis// Original error: Cannot find module 'ioredis'| Export | What it does |
|---|---|
lazyImportModule<T>(name, options?) | import(name), or throw a “missing peer dependency” error. |
LazyImportOptions | { context?, installHint? } — who needed it, and how to install it. |
This is the pattern the framework’s own brokers, caches and persistence
backends are built on, and the reason every one of them fails the same way: the
module must not be a hard dependency, so the import has to be dynamic, so the
default failure mode is a bare Cannot find module that says nothing about
which package is missing or what to do about it. Pairing it with Lazy — also
exported from the root entry point — means the import happens once, on first
use, rather than at construction.
Options builders and validators
Section titled “Options builders and validators”OptionsBuilder and OptionsValidator are the two base classes behind every
XOptions family in the framework — MqttOptions, SqliteJournalOptions,
ActorSystemOptions and the rest. You do not need them to use those options;
you need them to write your own in the same shape.
import { OptionsBuilder, OptionsValidator } from 'actor-ts';
type MyOptionsType = { readonly port?: number; readonly host?: string };
class MyOptionsBuilder extends OptionsBuilder<MyOptionsType> { withPort(port: number): this { return this.set('port', port); } withHost(host: string): this { return this.set('host', host); }}
class MyOptionsValidator extends OptionsValidator<MyOptionsType> { constructor() { super('MyOptions'); }
protected rules(_settings: Partial<MyOptionsType>): void { this.port('port'); // no-op when unset; throws OptionsError otherwise this.nonEmptyString('host'); }}A builder is its settings: the protected set writes each field as an own
enumerable property, so an instance is structurally a bag of the fields you set
and a plain object is interchangeable with it.
The check helpers (port, positiveNumber, positiveInt, nonNegativeInt,
numberInRange, oneOf, nonEmptyString, nonEmptyArray, url, and fail
for bespoke rules) take only the field name — it is typo-checked against
your options type, and a helper on a field of the wrong type is a compile
error. Every one is a no-op when the field is undefined, so an unset optional
always passes and required-ness stays wherever you enforce it. A rejected value
throws OptionsError, exported alongside so you can catch it specifically —
and when the rejected value is a URL, url reports it with its credentials
masked (Logging a URL without logging the password, above).
Validation runs once, at consume time, on the merged settings — so the builder, a plain object and HOCON are all covered, and cross-field rules see the final values. See configuration for how the layers resolve.
The whole toolbox — actor-ts/util
Section titled “The whole toolbox — actor-ts/util”Everything above is on the root entry point because you meet it while using the
framework. The rest of src/util/ solves problems that are one step further
out, and it is reachable on its own subpath:
import { TokenBucket, mergeOptions, wrapError } from 'actor-ts/util';The subpath is a superset: every name the root carries is on it too, so a file
that needs some and mergeOptions can take both from actor-ts/util rather
than importing twice.
| Export | What it does |
|---|---|
mergeOptions(defaults, fromConfig, explicit) | The one implementation of the options precedence explicit > HOCON > defaults. undefined on a higher layer means “not set” and falls through instead of blanking out the layer below — which is what you want, and not what a plain spread does. |
stripUndefined(partial) | Drops the keys whose value is undefined, which is how mergeOptions gets that property. |
TokenBucket | Rate limiting with a qps refill rate and a burst capacity, refilled lazily from elapsed time — no background timer. The clock is injectable, so a test advances time instead of waiting for it. |
wrapError(error, ErrorClass, message) | Re-throw a caught exception as a typed framework error with a contextual message, carrying the original as cause. An error already of the target class is returned unchanged rather than wrapped twice. |
escapeHtml, html, rawHtml, SafeHtml | Escaping for HTML element content and quoted attribute values. The html tagged template escapes every interpolation by default; rawHtml is the escape hatch for a string you have already made safe. Not a sanitizer for untrusted markup. |
stripTrailing(value, char), stripSurrounding(value, char) | Strip a repeated character off the ends in linear time. The regex spelling of this backtracks quadratically, which matters when the value is a request path or a hostname a remote peer chose. |
parseCidr, cidrMatches, isCidrEntry | CIDR parsing and matching, IPv4 and IPv6, with IPv4-mapped IPv6 handled so a plain IPv4 range still matches a dual-stack peer. |
parseAddressPin, addressMatchesPins, addressPinRejection | The address-pin rules built on those: an entry is a CIDR (matched against IPs) or a host suffix (matched against hostnames on a label boundary, so evilsvc.cluster.local does not slip past svc.cluster.local). addressPinRejection returns the reason an entry is unusable, for your own validator to report. |
DEFAULT_ASK_TIMEOUT_MS, DEFAULT_GOSSIP_INTERVAL_MS, DEFAULT_EXPLAIN_CAPACITY | The cross-subsystem defaults, so a timeout of your own that has to stay below the ask timeout can read it rather than copy the number. |
PATH_TRAVERSAL_SEGMENTS, MAXIMUM_DRAW_ATTEMPTS | The traversal denylist actor paths and persistence ids are both checked against, and the bound a uniqueness redraw gives up at. |
Where to next
Section titled “Where to next”- Logging — where
safeStringifyusually ends up. - Spawning actors — naming, and what an actor path exposes.
- Persistent actors — what state may contain, and how it round-trips.
- Configuration — how options, HOCON and defaults layer.
- Installation — which of the framework’s own dependencies are optional.
