Deprecate
Runtime deprecation-warning system for the framework's LTS contract. Operators see a one-time stderr warning the first time deprecated surface is used, naming the version it was deprecated in and the version it will be removed in — so behavior changes ship visible at least one minor before the breakage lands in a major.
Three usage shapes:
- warn(name, opts) — emit a warning at the call site of an inline deprecated path. - wrap(fn, name, opts) — return a wrapper around the replacement function so calls to the old name auto-warn and delegate. - alias(target, oldKey, newKey, opts) — define oldKey on target as a getter/setter that warns on access and reads through to newKey.
Warnings dedupe by (name, since) — calling warn ten thousand times with the same args emits a single stderr line; the per-name call counter is still incremented so list() reflects real usage volume for ops dashboards.
BLAMEJS_DEPRECATIONS env var controls runtime behavior:
- "warn" — stderr warning on first use (default outside production). - "silent" — skip entirely (default in production; operators do not want stderr noise from deprecated paths in code they do not own). - "error" — throw on first use; development tool to surface every deprecated call site as a hard failure during a sweep.
Mode resolution: explicit env var first, then "silent" when NODE_ENV=production, otherwise "warn".
b.deprecate.warn(name, opts) #
{
since: string, // required; semver this surface was deprecated in
removeIn: string, // required; semver of planned removal
message: string, // optional human-readable replacement guidance
hint: string, // optional cross-reference (MIGRATING.md anchor)
}Emit a deprecation warning for an inline call site. First call for a given (name, since) pair writes a single line to stderr in "warn" mode, throws DeprecateError in "error" mode, and is suppressed in "silent" mode. Subsequent calls dedupe but still increment the per-name call counter so list() reports real usage volume. Throws DeprecateError (deprecate/bad-name) on missing name and (deprecate/bad-opts) when since or removeIn are missing or empty.
var b = require("@blamejs/core");
b.deprecate.warn("auth.legacyVerify", {
since: "0.2.0",
removeIn: "0.4.0",
message: "use auth.password.verify(stored, plain) instead",
hint: "see MIGRATING.md#0-2-to-0-4",
});
// → undefined (stderr: [blamejs:deprecated] auth.legacyVerify (since 0.2.0); removed in 0.4.0 — ...)b.deprecate.wrap(fn, name, opts) #
{
since: string, // required; semver this surface was deprecated in
removeIn: string, // required; semver of planned removal
message: string, // optional human-readable replacement guidance
hint: string, // optional cross-reference (MIGRATING.md anchor)
}Return a function that warns on first invocation then delegates to fn with the same this and arguments. Use to keep the old export name working through one minor version after rename. The wrapper's .name is set to warn. Throws DeprecateError (deprecate/bad-target) when fn is not a function and (deprecate/bad-name) on missing name.
var b = require("@blamejs/core");
function passwordVerify(stored, plain) { return stored === plain; }
var legacyVerify = b.deprecate.wrap(passwordVerify, "auth.legacyVerify", {
since: "0.2.0",
removeIn: "0.4.0",
message: "renamed to auth.password.verify",
});
var ok = legacyVerify("stored", "plain");
// → false (stderr warns once on first call)b.deprecate.alias(target, oldKey, newKey, opts) #
{
since: string, // required; semver this surface was deprecated in
removeIn: string, // required; semver of planned removal
message: string, // optional override; defaults to "use 'newKey' instead"
hint: string, // optional cross-reference (MIGRATING.md anchor)
aliasName: string, // optional override for the warned identifier
}Define a getter/setter on target.oldKey that warns on access and reads/writes through to target.newKey. Use to keep a renamed property accessible for one minor without losing visibility into who still reads the old name. The aliased property is non- enumerable (so it does not leak into Object.keys / JSON serialization) but configurable so tests can redefine it. Throws DeprecateError (deprecate/bad-target) when target is not an object and (deprecate/bad-name) on missing oldKey / newKey.
var b = require("@blamejs/core");
var settings = { timeout: 5000 };
b.deprecate.alias(settings, "timeoutMs", "timeout", {
since: "0.3.0",
removeIn: "0.5.0",
});
var v = settings.timeoutMs;
// → 5000 (stderr warns once on first read)b.deprecate.list() #
Return an array of every deprecated identifier hit during this process's lifetime — { name, since, removeIn, callCount, firstSeen }. Sorted most-frequent first, ties broken by earliest firstSeen. Use from an ops dashboard or boot diagnostic to surface which deprecated paths the running deployment still exercises so the team can prioritize migrations before the removeIn major lands.
var b = require("@blamejs/core");
b.deprecate.warn("auth.legacyVerify", { since: "0.2.0", removeIn: "0.4.0" });
var rows = b.deprecate.list();
// → [{ name: "auth.legacyVerify", since: "0.2.0", removeIn: "0.4.0",
// callCount: 1, firstSeen: "2026-05-09T12:00:00.000Z" }]b.deprecate.reset() #
Clear the seen-set so subsequent warn / wrap / alias calls re-emit their first-use warnings. Used by tests that exercise the deprecation path repeatedly; not meant for production code, where the dedupe is intentional.
var b = require("@blamejs/core");
b.deprecate.warn("auth.legacyVerify", { since: "0.2.0", removeIn: "0.4.0" });
b.deprecate.reset();
var seen = b.deprecate.list();
// → []b.deprecate.getMode() #
Return the resolved deprecation mode for the current process — "warn", "silent", or "error". Resolution order: explicit BLAMEJS_DEPRECATIONS env var, then "silent" when NODE_ENV=production, otherwise "warn". Use from boot diagnostics or test setup to confirm the active posture before exercising deprecated paths.
var b = require("@blamejs/core");
var mode = b.deprecate.getMode();
// → "warn" (development default)
// → "silent" (NODE_ENV=production)
// → "error" (BLAMEJS_DEPRECATIONS=error)Last updated 2026-08-08T16:39:49.652Z by seeder.