type-fns 1.21.3 → 1.21.5

package/dist/companions/asFrozenDeep.d.ts

@@ -0,0 +1,52 @@
+import type { FrozenDeep } from '../types/FrozenDeep';
+/**
+ * .what = a companion to the `FrozenDeep` type; freezes a value deep, in place, and returns it
+ *         typed as `FrozenDeep<T>`
+ * .why = the type announces "readonly all the way down"; this enforces it at runtime, so a write
+ *        the type refuses also throws, and the two cannot drift apart
+ *
+ * .note = in place, deliberately. it returns the same reference (`asFrozenDeep(x) === x`), since a
+ *         copy would break identity for every holder of the original, and would leave that
+ *         original writable
+ * .note = all or none. the whole graph is checked before any of it is frozen, so a refusal leaves
+ *         the value untouched
+ * .note = idempotent. a second call on a value it froze returns the same reference, no throw — even
+ *         from a second loaded copy of this package, via a `Symbol.for` mark on each value
+ * .note = a built-in whose mutators write an internal slot — `Map`, `Set`, `WeakMap`, `WeakSet`,
+ *         `Date`, `DataView`, `RegExp` (`compile`), `ArrayBuffer` (`resize`, `transfer`) — has each
+ *         mutator refused at runtime with a `ConstraintError` that names the fix, which a bare
+ *         `Object.freeze` does not. its reads are untouched
+ * .note = a write onto a frozen object, array, or function prop throws the engine's own
+ *         `TypeError` in strict mode (every es module) and is ignored in sloppy mode, per
+ *         `Object.freeze`. to change a value, copy it and change the copy:
+ *         `{ ...frozen, page: { ...frozen.page, limit: 50 } }`, `[...frozen.tags, 'push']`
+ * .note = a primitive, branded or plain, is returned as-is
+ * .note = it reaches non-enumerable own props too, so `new Error('x', { cause })` freezes `cause`.
+ *         it never enters a function's `prototype`, which every instance of a class shares
+ * .note = it throws a `ConstraintError` on what it can not freeze: a typed array with elements, a
+ *         global or sticky `RegExp` (its reads write `lastIndex`), a slot-mutator built-in already
+ *         sealed by another freeze, and one with a mutator pinned as an own non-configurable prop.
+ *         each names the fix, and the `path` in the value where the refused object sits
+ *         (`value.page.bytes`, `value.byKey.get('sms')`)
+ * .note = it freezes every holder's view of a shared sub-object, since it freezes in place: an
+ *         object the caller shares with another holder is frozen for that holder too
+ * .bound = what it does not stop:
+ *   - the bytes of an `ArrayBuffer`, or of a `DataView`'s buffer, stay writable through any view
+ *     built on that buffer; a freeze locks the object, never its memory
+ *   - a class instance's `#private` fields stay writable through its own methods; a private field
+ *     is no property, so `Object.freeze` can not reach it
+ *   - a value a getter returns is not frozen, though the type calls it frozen deep; the walk never
+ *     invokes an accessor, so it runs no caller code
+ *   - a refused mutator still runs when reached through its prototype, as in
+ *     `Map.prototype.set.call(frozen, k, v)` or `Reflect.apply`; the shadow is an own prop, and a
+ *     `Proxy` that would close it breaks identity and `instanceof` (F12)
+ *
+ * example:
+ * ```ts
+ * const event = asFrozenDeep({ page: { limit: 10 }, tags: ['sms'] });
+ * event.page.limit = 50;   // ⛔ tsc refuses; at runtime, a TypeError
+ * event.tags.push('push'); // ⛔ tsc refuses; at runtime, a TypeError
+ * const next = { ...event, page: { ...event.page, limit: 50 } }; // ✅ a copy is writable
+ * ```
+ */
+export declare const asFrozenDeep: <T>(value: T) => FrozenDeep<T>;

package/dist/companions/asFrozenDeep.js

@@ -0,0 +1,344 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.asFrozenDeep = void 0;
+const helpful_errors_1 = require("helpful-errors");
+const isPresent_1 = require("../checks/isPresent");
+const kindsWithSlotMutators_1 = require("./kindsWithSlotMutators");
+/**
+ * .what = the mark `asFrozenDeep` sets on each object whose mutators it refused
+ * .why = a second call must skip what a first call froze, and tell it apart from an object sealed
+ *        by any other freeze, whose mutators can no longer be shadowed
+ * .note = `Symbol.for`, so two loaded copies of this package read one mark; a marked object stays
+ *         idempotent across duplicate installs
+ * .note = set as a non-enumerable own prop, so `Object.keys`, json, and the walk skip it
+ */
+const mutatorsRefusedMark = Symbol.for('type-fns.asFrozenDeep.mutatorsRefused');
+/**
+ * .what = the slot-mutator kind a value is an instance of; else null
+ * .why = one lookup feeds the check pass and the freeze pass alike
+ */
+const getOneKindWithSlotMutators = (input) => kindsWithSlotMutators_1.kindsWithSlotMutators.find((kind) => input.value instanceof kind.of) ?? null;
+/**
+ * .what = the mutators of a value that `asFrozenDeep` has yet to refuse; else none
+ * .why = a value already marked owes none, and a value of no slot-mutator kind owes none
+ */
+const getAllMutatorsUnrefused = (input) => {
+    // a value this package already refused owes none
+    if (Object.hasOwn(input.value, mutatorsRefusedMark))
+        return [];
+    // a slot-mutator kind owes its mutators; any other object owes none
+    return getOneKindWithSlotMutators({ value: input.value })?.mutators ?? [];
+};
+/**
+ * .what = true for the one own property the walk must never enter: a function's `prototype`
+ * .why = a class's `prototype` holds the methods every instance shares; to freeze it would freeze
+ *        every instance's methods, far past the value the caller passed
+ */
+const isPrototypeOfFunction = (input) => typeof input.of === 'function' && input.key === 'prototype';
+/**
+ * .what = the key and value of every own data property, symbol keys and non-enumerable keys included
+ * .why = `FrozenDeep` maps every key deep, so the walk must reach every value the type claims is
+ *        frozen — `Object.values` skips symbol keys, and enumerability hides `err.cause`
+ * .note = data properties only: an accessor is never invoked, so the walk runs no caller code
+ * .note = a function's `prototype` stays out of the walk (see `isPrototypeOfFunction`)
+ */
+const getAllOwnDataEntries = (input) => Reflect.ownKeys(input.of)
+    .filter((key) => !isPrototypeOfFunction({ of: input.of, key }))
+    .map((key) => ({
+    key,
+    descriptor: Reflect.getOwnPropertyDescriptor(input.of, key),
+}))
+    .filter((own) => (0, isPresent_1.isPresent)(own.descriptor) && 'value' in own.descriptor)
+    .map((own) => ({ key: own.key, value: own.descriptor?.value }));
+/**
+ * .what = a string as a single-quoted js literal
+ * .why = a path sits inside the json metadata of a refusal; a double-quoted key would print there
+ *        as `\"sms\"`, where a single-quoted one prints as `'sms'`
+ */
+const asQuotedLiteral = (input) => `'${input.of.replace(/\\/g, '\\\\').replace(/'/g, "\\'")}'`;
+/**
+ * .what = the path to an own property, from its holder's path, in js accessor notation
+ * .why = a refusal deep in a payload must say where it sits, or the caller hunts for it
+ * .note = `value.page`, `value.tags[0]`, `value['a-b']`, `value[Symbol(tag)]`
+ */
+const asPathToOwnProperty = (input) => {
+    const { holder, key } = input;
+    if (typeof key === 'symbol')
+        return `${holder.path}[${String(key)}]`;
+    if (Array.isArray(holder.value) && /^\d+$/.test(key))
+        return `${holder.path}[${key}]`;
+    if (/^[A-Za-z_$][\w$]*$/.test(key))
+        return `${holder.path}.${key}`;
+    return `${holder.path}[${asQuotedLiteral({ of: key })}]`;
+};
+/**
+ * .what = the path to a map value, from the map's path, in js accessor notation
+ * .note = `.get('sms')` for a string, number, or boolean key; else the entry's position,
+ *         `[...value.byKey.values()][0]`, since an object key has no literal to name it
+ */
+const asPathToMapValue = (input) => {
+    const { map, key, position } = input;
+    if (typeof key === 'string')
+        return `${map.path}.get(${asQuotedLiteral({ of: key })})`;
+    if (typeof key === 'number' || typeof key === 'boolean')
+        return `${map.path}.get(${String(key)})`;
+    return `[...${map.path}.values()][${position}]`;
+};
+/**
+ * .what = every object reachable from a value, each once, in visit order, with the path that
+ *         first reached it
+ * .why = a pure read of the graph, so every refusal is found before any freeze happens, and each
+ *        refusal can name where in the value it sits
+ * .note = walks own data values (non-enumerable ones too), map keys and values, and set members;
+ *         never a function's `prototype`; a typed array's elements
+ *         are numbers, so its interior is not walked. a weak collection can not be enumerated,
+ *         so its entries are not walked either
+ * .note = a shared sub-object is named by the first path that reached it
+ * .note = a general graph walk, private while this is its one caller; lift it to `src/` when a
+ *         second caller (a deep equal, a deep clone) appears
+ */
+const getAllReachableObjects = (input) => {
+    const reached = new Map();
+    /**
+     * .what = records one value at its path, then descends into what it holds
+     * .why = one recursion for every shape; the `reached` check ends a cycle and dedupes a shared
+     *        sub-object
+     */
+    const visit = (step) => {
+        // skip a primitive, and a value already reached by another path
+        const { value, path } = step;
+        if (value === null)
+            return;
+        if (typeof value !== 'object' && typeof value !== 'function')
+            return;
+        if (reached.has(value))
+            return;
+        reached.set(value, path);
+        // descend into entries, members, and own data values
+        if (ArrayBuffer.isView(value))
+            return;
+        if (value instanceof Map)
+            [...value].forEach(([key, entry], position) => {
+                visit({ value: key, path: `[...${path}.keys()][${position}]` });
+                visit({
+                    value: entry,
+                    path: asPathToMapValue({ map: { path }, key, position }),
+                });
+            });
+        if (value instanceof Set)
+            [...value].forEach((member, position) => visit({ value: member, path: `[...${path}][${position}]` }));
+        for (const own of getAllOwnDataEntries({ of: value }))
+            visit({
+                value: own.value,
+                path: asPathToOwnProperty({ holder: { path, value }, key: own.key }),
+            });
+    };
+    visit({ value: input.from, path: 'value' });
+    return [...reached].map(([object, path]) => ({ object, path }));
+};
+/**
+ * .what = refuses a typed array with elements; else null
+ * .why = `Object.freeze` throws on a non-empty typed array, since its index slots can not be sealed
+ * .note = a `DataView` has no index slots, so it freezes fine; its setters are refused instead
+ */
+const getOneRefusalOfTypedArray = (input) => {
+    const { value, path } = input;
+    if (!ArrayBuffer.isView(value))
+        return null;
+    if (value instanceof DataView)
+        return null;
+    if (value.byteLength === 0)
+        return null;
+    return new helpful_errors_1.ConstraintError('asFrozenDeep can not freeze a typed array with elements', {
+        path,
+        kind: value.constructor.name,
+        byteLength: value.byteLength,
+        hint: 'convert it to a plain array first, e.g. Array.from(bytes)',
+    });
+};
+/**
+ * .what = refuses a global or sticky `RegExp`; else null
+ * .why = each `.exec()` / `.test()` on one writes `lastIndex`, so once frozen, a plain read throws
+ */
+const getOneRefusalOfRegExpWithLastIndex = (input) => {
+    const { value, path } = input;
+    if (!(value instanceof RegExp))
+        return null;
+    if (!value.global && !value.sticky)
+        return null;
+    return new helpful_errors_1.ConstraintError('asFrozenDeep can not freeze a global or sticky RegExp, since each exec writes its lastIndex', {
+        path,
+        kind: 'RegExp',
+        flags: value.flags,
+        hint: "copy it without the g and y flags first: new RegExp(re.source, re.flags.replace(/[gy]/g, ''))",
+    });
+};
+/**
+ * .what = a class name with its indefinite article, `a Map` or `an ArrayBuffer`
+ * .why = a refusal names the kind in prose; `a ArrayBuffer` reads as a typo
+ */
+const asKindWithArticle = (input) => `${/^[AEIOU]/i.test(input.kind) ? 'an' : 'a'} ${input.kind}`;
+/**
+ * .what = refuses a slot-mutator kind sealed by a freeze other than `asFrozenDeep`; else null
+ * .why = a sealed object takes no new own props, so its mutators can no longer be shadowed
+ */
+const getOneRefusalOfSealedElsewhere = (input) => {
+    const { value, path } = input;
+    if (getAllMutatorsUnrefused({ value }).length === 0)
+        return null;
+    if (Object.isExtensible(value))
+        return null;
+    const kind = getOneKindWithSlotMutators({ value });
+    return new helpful_errors_1.ConstraintError(`asFrozenDeep can not freeze ${asKindWithArticle({ kind: value.constructor.name })} already sealed via Object.freeze, Object.seal, or Object.preventExtensions`, {
+        path,
+        kind: value.constructor.name,
+        hint: `pass it to asFrozenDeep before any other freeze, or copy it first: ${kind?.copy}`,
+    });
+};
+/**
+ * .what = refuses a slot-mutator kind with a mutator pinned as an own non-configurable prop; else null
+ * .why = `Object.defineProperty` can not replace it, so the shadow would throw mid-freeze
+ */
+const getOneRefusalOfMutatorPinned = (input) => {
+    const { value, path } = input;
+    const pinned = getAllMutatorsUnrefused({ value }).find((mutator) => Reflect.getOwnPropertyDescriptor(value, mutator)?.configurable === false);
+    if (!pinned)
+        return null;
+    const kind = getOneKindWithSlotMutators({ value });
+    return new helpful_errors_1.ConstraintError(`asFrozenDeep can not freeze ${asKindWithArticle({ kind: value.constructor.name })} whose mutator is pinned as an own non-configurable property`, {
+        path,
+        kind: value.constructor.name,
+        mutator: pinned,
+        hint: `copy it first, which carries no own props: ${kind?.copy}`,
+    });
+};
+/**
+ * .what = every check a single object must clear before `asFrozenDeep` freezes it
+ * .why = one list, so a new refusal lands as one new entry
+ */
+const freezeRefusalChecks = [
+    getOneRefusalOfTypedArray,
+    getOneRefusalOfRegExpWithLastIndex,
+    getOneRefusalOfSealedElsewhere,
+    getOneRefusalOfMutatorPinned,
+];
+/**
+ * .what = the first refusal any object of a graph earns, which names the object's path; else null
+ * .why = lets the walk refuse the whole graph before it touches any of it
+ */
+const getOneFreezeRefusalOfGraph = (input) => input.reached
+    .flatMap((each) => freezeRefusalChecks.map((check) => check({ value: each.object, path: each.path })))
+    .find(isPresent_1.isPresent) ?? null;
+/**
+ * .what = shadows each named mutator with an own method that throws, then marks the value
+ * .why = the only way to refuse `map.set()` or `date.setFullYear()` at runtime and keep the same
+ *        instance — a `Proxy` or a copy would break identity and `instanceof`
+ * .note = the shadows and the mark are non-enumerable, so `Object.keys` and json do not see them
+ */
+const setMutatorsRefused = (input) => {
+    // shadow each mutator with a method that names the fix
+    const kind = input.value.constructor.name;
+    const copy = getOneKindWithSlotMutators({ value: input.value })?.copy;
+    for (const mutator of input.mutators)
+        Object.defineProperty(input.value, mutator, {
+            value: () => {
+                throw new helpful_errors_1.ConstraintError(`a frozen ${kind} refuses .${mutator}()`, {
+                    kind,
+                    mutator,
+                    hint: `copy it first, then mutate the copy: ${copy}`,
+                });
+            },
+            enumerable: false,
+            writable: false,
+            configurable: false,
+        });
+    // mark it, so a later call — from this copy of the package or another — skips it
+    Object.defineProperty(input.value, mutatorsRefusedMark, {
+        value: true,
+        enumerable: false,
+        writable: false,
+        configurable: false,
+    });
+};
+/**
+ * .what = freezes one object; a slot-mutator kind also has its mutators refused, once
+ * .why = the single place this module writes to a caller's value
+ */
+const setFrozen = (input) => {
+    // refuse a slot-mutator kind's mutators, unless a prior call already did
+    const mutators = getAllMutatorsUnrefused({ value: input.value });
+    if (mutators.length > 0)
+        setMutatorsRefused({ value: input.value, mutators });
+    // freeze the object itself; a no-op if already frozen
+    Object.freeze(input.value);
+};
+/**
+ * .what = a companion to the `FrozenDeep` type; freezes a value deep, in place, and returns it
+ *         typed as `FrozenDeep<T>`
+ * .why = the type announces "readonly all the way down"; this enforces it at runtime, so a write
+ *        the type refuses also throws, and the two cannot drift apart
+ *
+ * .note = in place, deliberately. it returns the same reference (`asFrozenDeep(x) === x`), since a
+ *         copy would break identity for every holder of the original, and would leave that
+ *         original writable
+ * .note = all or none. the whole graph is checked before any of it is frozen, so a refusal leaves
+ *         the value untouched
+ * .note = idempotent. a second call on a value it froze returns the same reference, no throw — even
+ *         from a second loaded copy of this package, via a `Symbol.for` mark on each value
+ * .note = a built-in whose mutators write an internal slot — `Map`, `Set`, `WeakMap`, `WeakSet`,
+ *         `Date`, `DataView`, `RegExp` (`compile`), `ArrayBuffer` (`resize`, `transfer`) — has each
+ *         mutator refused at runtime with a `ConstraintError` that names the fix, which a bare
+ *         `Object.freeze` does not. its reads are untouched
+ * .note = a write onto a frozen object, array, or function prop throws the engine's own
+ *         `TypeError` in strict mode (every es module) and is ignored in sloppy mode, per
+ *         `Object.freeze`. to change a value, copy it and change the copy:
+ *         `{ ...frozen, page: { ...frozen.page, limit: 50 } }`, `[...frozen.tags, 'push']`
+ * .note = a primitive, branded or plain, is returned as-is
+ * .note = it reaches non-enumerable own props too, so `new Error('x', { cause })` freezes `cause`.
+ *         it never enters a function's `prototype`, which every instance of a class shares
+ * .note = it throws a `ConstraintError` on what it can not freeze: a typed array with elements, a
+ *         global or sticky `RegExp` (its reads write `lastIndex`), a slot-mutator built-in already
+ *         sealed by another freeze, and one with a mutator pinned as an own non-configurable prop.
+ *         each names the fix, and the `path` in the value where the refused object sits
+ *         (`value.page.bytes`, `value.byKey.get('sms')`)
+ * .note = it freezes every holder's view of a shared sub-object, since it freezes in place: an
+ *         object the caller shares with another holder is frozen for that holder too
+ * .bound = what it does not stop:
+ *   - the bytes of an `ArrayBuffer`, or of a `DataView`'s buffer, stay writable through any view
+ *     built on that buffer; a freeze locks the object, never its memory
+ *   - a class instance's `#private` fields stay writable through its own methods; a private field
+ *     is no property, so `Object.freeze` can not reach it
+ *   - a value a getter returns is not frozen, though the type calls it frozen deep; the walk never
+ *     invokes an accessor, so it runs no caller code
+ *   - a refused mutator still runs when reached through its prototype, as in
+ *     `Map.prototype.set.call(frozen, k, v)` or `Reflect.apply`; the shadow is an own prop, and a
+ *     `Proxy` that would close it breaks identity and `instanceof` (F12)
+ *
+ * example:
+ * ```ts
+ * const event = asFrozenDeep({ page: { limit: 10 }, tags: ['sms'] });
+ * event.page.limit = 50;   // ⛔ tsc refuses; at runtime, a TypeError
+ * event.tags.push('push'); // ⛔ tsc refuses; at runtime, a TypeError
+ * const next = { ...event, page: { ...event.page, limit: 50 } }; // ✅ a copy is writable
+ * ```
+ */
+const asFrozenDeep = (value) => {
+    // find every object the value reaches, with its path
+    const reached = getAllReachableObjects({ from: value });
+    // refuse the whole graph if any object can not be frozen
+    const refusal = getOneFreezeRefusalOfGraph({ reached });
+    if (refusal)
+        throw refusal;
+    // freeze every object
+    for (const each of reached)
+        setFrozen({ value: each.object });
+    /**
+     * .why the cast = `FrozenDeep<T>` is a conditional type, so on an unresolved generic typescript
+     *        defers it and cannot prove `T` satisfies it — a limit of the checker, never a gap in the
+     *        claim. the walk above is the proof, and it runs first
+     * .removal = drops if typescript ever proves a conditional type against its own input
+     */
+    return value;
+};
+exports.asFrozenDeep = asFrozenDeep;
+//# sourceMappingURL=asFrozenDeep.js.map

package/dist/companions/asFrozenDeep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"asFrozenDeep.js","sourceRoot":"","sources":["../../src/companions/asFrozenDeep.ts"],"names":[],"mappings":"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"}

package/dist/companions/kindsWithSlotMutators.d.ts

@@ -0,0 +1,32 @@
+/**
+ * .what = the built-ins whose mutators write an internal slot, which `Object.freeze` can not stop
+ * .why = `map.set()`, `date.setFullYear()`, `view.setInt8()` each change a frozen object in
+ *        silence; each owes its mutators shadowed with throwers, and a copy recipe for the hint
+ * .note = a file of its own so the doc-drift clamp can read the list, not restate it; the package
+ *         root does not export it
+ */
+export declare const kindsWithSlotMutators: ({
+    of: WeakMapConstructor;
+    mutators: string[];
+    copy: string;
+} | {
+    of: WeakSetConstructor;
+    mutators: string[];
+    copy: string;
+} | {
+    of: DateConstructor;
+    mutators: string[];
+    copy: string;
+} | {
+    of: DataViewConstructor;
+    mutators: string[];
+    copy: string;
+} | {
+    of: RegExpConstructor;
+    mutators: string[];
+    copy: string;
+} | {
+    of: ArrayBufferConstructor;
+    mutators: string[];
+    copy: string;
+})[];

package/dist/companions/kindsWithSlotMutators.js

@@ -0,0 +1,51 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.kindsWithSlotMutators = void 0;
+/**
+ * .what = the names of every `set*` method on a prototype
+ * .why = `Date` and `DataView` each hold a closed family of setters; to read them from the
+ *        prototype keeps the list exact for the runtime at hand (e.g. `setFloat16` where present)
+ */
+const getAllSettersOf = (input) => Object.getOwnPropertyNames(input.prototype).filter((name) => name.startsWith('set'));
+/**
+ * .what = the built-ins whose mutators write an internal slot, which `Object.freeze` can not stop
+ * .why = `map.set()`, `date.setFullYear()`, `view.setInt8()` each change a frozen object in
+ *        silence; each owes its mutators shadowed with throwers, and a copy recipe for the hint
+ * .note = a file of its own so the doc-drift clamp can read the list, not restate it; the package
+ *         root does not export it
+ */
+exports.kindsWithSlotMutators = [
+    { of: Map, mutators: ['set', 'delete', 'clear'], copy: 'new Map(frozen)' },
+    { of: Set, mutators: ['add', 'delete', 'clear'], copy: 'new Set(frozen)' },
+    {
+        of: WeakMap,
+        mutators: ['set', 'delete'],
+        copy: 'a new WeakMap, refilled from the keys you hold',
+    },
+    {
+        of: WeakSet,
+        mutators: ['add', 'delete'],
+        copy: 'a new WeakSet, refilled from the members you hold',
+    },
+    {
+        of: Date,
+        mutators: getAllSettersOf({ prototype: Date.prototype }),
+        copy: 'new Date(frozen)',
+    },
+    {
+        of: DataView,
+        mutators: getAllSettersOf({ prototype: DataView.prototype }),
+        copy: 'new DataView(frozen.buffer.slice(0))',
+    },
+    {
+        of: RegExp,
+        mutators: ['compile'],
+        copy: 'new RegExp(frozen)',
+    },
+    {
+        of: ArrayBuffer,
+        mutators: ['resize', 'transfer', 'transferToFixedLength'].filter((name) => name in ArrayBuffer.prototype),
+        copy: 'frozen.slice(0)',
+    },
+];
+//# sourceMappingURL=kindsWithSlotMutators.js.map

package/dist/companions/kindsWithSlotMutators.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"kindsWithSlotMutators.js","sourceRoot":"","sources":["../../src/companions/kindsWithSlotMutators.ts"],"names":[],"mappings":";;;AAAA;;;;GAIG;AACH,MAAM,eAAe,GAAG,CAAC,KAA4B,EAAY,EAAE,CACjE,MAAM,CAAC,mBAAmB,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,MAAM,CAAC,CAAC,IAAI,EAAE,EAAE,CAC1D,IAAI,CAAC,UAAU,CAAC,KAAK,CAAC,CACvB,CAAC;AAEJ;;;;;;GAMG;AACU,QAAA,qBAAqB,GAAG;IACnC,EAAE,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE;IAC1E,EAAE,EAAE,EAAE,GAAG,EAAE,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,EAAE,OAAO,CAAC,EAAE,IAAI,EAAE,iBAAiB,EAAE;IAC1E;QACE,EAAE,EAAE,OAAO;QACX,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC;QAC3B,IAAI,EAAE,gDAAgD;KACvD;IACD;QACE,EAAE,EAAE,OAAO;QACX,QAAQ,EAAE,CAAC,KAAK,EAAE,QAAQ,CAAC;QAC3B,IAAI,EAAE,mDAAmD;KAC1D;IACD;QACE,EAAE,EAAE,IAAI;QACR,QAAQ,EAAE,eAAe,CAAC,EAAE,SAAS,EAAE,IAAI,CAAC,SAAS,EAAE,CAAC;QACxD,IAAI,EAAE,kBAAkB;KACzB;IACD;QACE,EAAE,EAAE,QAAQ;QACZ,QAAQ,EAAE,eAAe,CAAC,EAAE,SAAS,EAAE,QAAQ,CAAC,SAAS,EAAE,CAAC;QAC5D,IAAI,EAAE,sCAAsC;KAC7C;IACD;QACE,EAAE,EAAE,MAAM;QACV,QAAQ,EAAE,CAAC,SAAS,CAAC;QACrB,IAAI,EAAE,oBAAoB;KAC3B;IACD;QACE,EAAE,EAAE,WAAW;QACf,QAAQ,EAAE,CAAC,QAAQ,EAAE,UAAU,EAAE,uBAAuB,CAAC,CAAC,MAAM,CAC9D,CAAC,IAAI,EAAE,EAAE,CAAC,IAAI,IAAI,WAAW,CAAC,SAAS,CACxC;QACD,IAAI,EAAE,iBAAiB;KACxB;CACF,CAAC"}

package/dist/index.d.ts

@@ -9,11 +9,15 @@ export * from './checks/isNotPromise';
 export * from './checks/isNotUndefined';
 export * from './checks/isOfEnum';
 export * from './checks/isPresent';
+export * from './companions/asFrozenDeep';
 export * from './companions/omit';
 export * from './companions/pick';
 export * from './guards/assure';
+export * from './types/ArrayWith';
 export * from './types/DropFirst';
 export * from './types/Empty';
+export * from './types/FrozenDeep';
+export * from './types/HasMaybe';
 export * from './types/Literalize';
 export * from './types/PickAny';
 export * from './types/PickOne';

package/dist/index.js

@@ -25,11 +25,15 @@ __exportStar(require("./checks/isNotPromise"), exports);
 __exportStar(require("./checks/isNotUndefined"), exports);
 __exportStar(require("./checks/isOfEnum"), exports);
 __exportStar(require("./checks/isPresent"), exports);
+__exportStar(require("./companions/asFrozenDeep"), exports);
 __exportStar(require("./companions/omit"), exports);
 __exportStar(require("./companions/pick"), exports);
 __exportStar(require("./guards/assure"), exports);
+__exportStar(require("./types/ArrayWith"), exports);
 __exportStar(require("./types/DropFirst"), exports);
 __exportStar(require("./types/Empty"), exports);
+__exportStar(require("./types/FrozenDeep"), exports);
+__exportStar(require("./types/HasMaybe"), exports);
 __exportStar(require("./types/Literalize"), exports);
 __exportStar(require("./types/PickAny"), exports);
 __exportStar(require("./types/PickOne"), exports);

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA+B;AAC/B,uDAAqC;AACrC,mDAAiC;AACjC,uDAAqC;AACrC,sDAAoC;AACpC,mDAAiC;AACjC,qDAAmC;AACnC,wDAAsC;AACtC,0DAAwC;AACxC,oDAAkC;AAClC,qDAAmC;AACnC,oDAAkC;AAClC,oDAAkC;AAClC,kDAAgC;AAChC,oDAAkC;AAClC,gDAA8B;AAC9B,qDAAmC;AACnC,kDAAgC;AAChC,kDAAgC;AAChC,wDAAsC;AACtC,qDAAmC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,iDAA+B;AAC/B,uDAAqC;AACrC,mDAAiC;AACjC,uDAAqC;AACrC,sDAAoC;AACpC,mDAAiC;AACjC,qDAAmC;AACnC,wDAAsC;AACtC,0DAAwC;AACxC,oDAAkC;AAClC,qDAAmC;AACnC,4DAA0C;AAC1C,oDAAkC;AAClC,oDAAkC;AAClC,kDAAgC;AAChC,oDAAkC;AAClC,oDAAkC;AAClC,gDAA8B;AAC9B,qDAAmC;AACnC,mDAAiC;AACjC,qDAAmC;AACnC,kDAAgC;AAChC,kDAAgC;AAChC,wDAAsC;AACtC,qDAAmC"}

package/dist/types/FrozenDeep.d.ts

@@ -0,0 +1,63 @@
+/**
+ * .what = readonly all the way down, with every primitive left exactly as it is
+ * .why = typescript's `Readonly<T>` is one level deep, so `frozen.a.b = 1` compiles while a deep
+ *        runtime freeze throws on it. this type refuses the write at every depth, to match
+ *        `asFrozenDeep`, which enforces what this type announces
+ *
+ * .the family = `FrozenDeep<T>` maps any shape to its frozen form:
+ *   - primitive, branded or plain -> itself. a primitive has no interior to freeze; a branded
+ *     primitive (`string & { _brand }`) stays assignable back to its brand
+ *   - function                    -> its call signature, with its own props readonly
+ *   - `Map<K, V>`                 -> `FrozenMap<K, V>`
+ *   - `Set<T>`                    -> `FrozenSet<T>`
+ *   - array or tuple              -> a readonly array or readonly tuple; a tuple keeps its arity,
+ *                                    labels, and positions
+ *   - object                      -> every property readonly, every value frozen deep
+ *
+ * .note = there is no `FrozenArray`. an array freezes to `readonly T[]` and a tuple to a readonly
+ *         tuple, so one name could not cover both without the loss of a tuple's shape
+ *
+ * .bound = what this type does not refuse:
+ *   - a hand-off to a mutable OBJECT parameter compiles. typescript ignores `readonly` in
+ *     structural assignability, so `{ readonly a: 1 }` is assignable to `{ a: 1 }`. a mutable
+ *     ARRAY parameter is refused, since `ReadonlyArray` lacks the mutator methods
+ *   - a write through `any` compiles. `any` opts out of every check
+ *   - `Array.isArray(frozen)` narrows to `any[]`, which hands `.push` back. prefer a `typeof` or
+ *     a shape check on a frozen value
+ *   - a `Date`, `DataView`, `WeakMap`, `WeakSet`, `RegExp`, or `ArrayBuffer` keeps the object arm,
+ *     so its mutator methods (`setFullYear`, `setInt8`, `set`, `add`, `compile`, `resize`) still
+ *     type-check — the object arm guards props, not methods, and a frozen `Date` stays assignable
+ *     back to `Date`. `asFrozenDeep` refuses each of those calls at runtime with a `ConstraintError`
+ *   - a class instance's methods still type-check, so a method that writes a `#private` field
+ *     compiles; no freeze reaches a private field
+ *   - a getter's value is typed frozen deep, yet `asFrozenDeep` never invokes a getter, so the
+ *     object it returns stays writable at runtime
+ */
+export type FrozenDeep<T> = T extends string | number | boolean | bigint | symbol | null | undefined ? T : T extends (...args: never[]) => unknown ? FrozenFunction<T> : T extends ReadonlyMap<infer TKey, infer TValue> ? FrozenMap<TKey, TValue> : T extends ReadonlySet<infer TItem> ? FrozenSet<TItem> : T extends object ? {
+    readonly [TKey in keyof T]: FrozenDeep<T[TKey]>;
+} : T;
+/**
+ * .what = a map whose mutators are absent and whose keys and values are frozen deep
+ * .why = `ReadonlyMap<K, V>` alone refuses `.set` yet leaves each value writable; this freezes both
+ */
+export type FrozenMap<TKey, TValue> = ReadonlyMap<FrozenDeep<TKey>, FrozenDeep<TValue>>;
+/**
+ * .what = a set whose mutators are absent and whose members are frozen deep
+ * .why = `ReadonlySet<T>` alone refuses `.add` yet leaves each member writable; this freezes both
+ */
+export type FrozenSet<TItem> = ReadonlySet<FrozenDeep<TItem>>;
+/**
+ * .what = a function with its call signature kept and its own props readonly
+ * .why = a function is an object too, and the runtime freeze refuses a write onto its props
+ * .note = a function with no own props passes through whole, so its generics and overloads survive.
+ *         a function WITH own props is rebuilt from `Parameters` / `ReturnType`, since an
+ *         intersection with `T` would keep each prop writable (a prop is readonly in an
+ *         intersection only where every member marks it so). the rebuild keeps one call
+ *         signature, so a generic or overloaded function with own props narrows to its last one
+ */
+type FrozenFunction<T extends (...args: never[]) => unknown> = [
+    keyof T
+] extends [never] ? T : ((...args: Parameters<T>) => ReturnType<T>) & {
+    readonly [TKey in keyof T]: FrozenDeep<T[TKey]>;
+};
+export {};

package/dist/types/FrozenDeep.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=FrozenDeep.js.map

package/dist/types/FrozenDeep.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"FrozenDeep.js","sourceRoot":"","sources":["../../src/types/FrozenDeep.ts"],"names":[],"mappings":""}

package/dist/types/HasMaybe.d.ts

@@ -0,0 +1,17 @@
+/**
+ * makes the listed key(s) `K` of `T` optional — the make-maybe companion of the
+ * make-required (`HasMetadata`) / omit (`OmitMetadata`) trio.
+ *
+ * use when a value's key is authored without it, then bound at a later
+ * lifecycle stage (e.g. a domain key like `exid` known only at activation).
+ *
+ * for example, `HasMaybe<{ role: string; exid: string }, 'exid'>` produces
+ * `{ role: string; exid?: string }`.
+ *
+ * note:
+ * - this type preserves all non-`K` keys exactly (required keys stay required)
+ * - this type only loosens the listed `K` — it does not add keys and does not
+ *   touch any key outside `K`
+ * - `K extends keyof T` — a key not on `T` is a compile error
+ */
+export type HasMaybe<T extends Record<string, any>, K extends keyof T> = Omit<T, K> & Partial<Pick<T, K>>;

package/dist/types/HasMaybe.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=HasMaybe.js.map

package/dist/types/HasMaybe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"HasMaybe.js","sourceRoot":"","sources":["../../src/types/HasMaybe.ts"],"names":[],"mappings":""}

package/package.json

@@ -2,7 +2,7 @@
   "name": "type-fns",
   "author": "ehmpathy",
   "description": "A set of types, type checks, and type guards for simpler, safer, and easier to read code.",
-  "version": "1.21.3",
+  "version": "1.21.5",
   "repository": "ehmpathy/type-fns",
   "homepage": "https://github.com/ehmpathy/type-fns",
   "keywords": [
@@ -55,7 +55,7 @@
     "preversion": "npm run prepush",
     "postversion": "git push origin HEAD --tags --no-verify",
     "prepare:husky": "husky install && chmod ug+x .husky/*",
-    "prepare:rhachet": "rhachet init --keys --hooks --roles mechanic behaver driver reviewer librarian ergonomist architect",
+    "prepare:rhachet": "rhachet init --hooks --roles mechanic behaver driver architect ergonomist reviewer dreamer dispatcher",
     "prepare": "if [ -e .git ] && [ -z $CI ]; then npm run prepare:husky && npm run prepare:rhachet; fi",
     "test:lint:cycles": "dpdm --no-warning --no-tree --exit-code circular:1 --exclude '^$' 'src/**/*.ts'",
     "upgrade:rhachet": "rhachet upgrade"
@@ -87,12 +87,13 @@
     "esbuild-register": "3.6.0",
     "husky": "8.0.3",
     "jest": "30.2.0",
-    "rhachet": "1.39.9",
-    "rhachet-brains-anthropic": "0.4.0",
+    "rhachet": "1.48.0",
+    "rhachet-brains-anthropic": "0.4.3",
+    "rhachet-brains-fireworksai": "0.2.3",
     "rhachet-brains-xai": "0.3.3",
-    "rhachet-roles-bhrain": "0.23.11",
-    "rhachet-roles-bhuild": "0.17.1",
-    "rhachet-roles-ehmpathy": "1.34.25",
+    "rhachet-roles-bhrain": "0.37.2",
+    "rhachet-roles-bhuild": "0.21.36",
+    "rhachet-roles-ehmpathy": "1.39.1",
     "test-fns": "1.15.8",
     "ts-jest": "29.1.3",
     "ts-node": "10.9.2",

package/readme.md

@@ -101,7 +101,28 @@ const str: string = strStr[0];
 const num: number = numStrStr[0];
 ```
 
-Useful, for example, if you want to change the first parameter of a function while keeping the rest the same.
+useful, for example, to change the first parameter of a function while the rest stay the same.
+
+### `FrozenDeep`
+
+the generic type `FrozenDeep` is readonly all the way down, where `Readonly` stops at one level. every primitive, branded primitives included, stays exactly as it is.
+
+```ts
+import { FrozenDeep } from 'type-fns';
+
+type IsoTimeStamp = string & { _dglo: 'iso-time.IsoTimeStamp' };
+type Event = { at: IsoTimeStamp; page: { limit: number }; tags: string[]; seen: Map<string, number> };
+
+declare const event: FrozenDeep<Event>;
+event.page.limit = 50;          // 🛑 readonly at depth two
+event.tags.push('push');        // 🛑 a readonly array has no push
+event.seen.set('sms', 1);       // 🛑 a FrozenMap has no set
+const at: IsoTimeStamp = event.at; // ✅ a branded primitive stays assignable back
+```
+
+one bound to know: a frozen object still passes into a parameter typed as a mutable object, since typescript does not check `readonly` on object props at assignment. a frozen array does not pass into a mutable array parameter, so an object with an array field inside is refused there too — the cause is the array, never a brand. declare the parameter `FrozenDeep<T>` to accept it.
+
+maps and sets freeze to `FrozenMap` / `FrozenSet`, also exported. pair it with `asFrozenDeep` to enforce the same at runtime.
 
 ## type guards
 
@@ -207,3 +228,36 @@ const processUser = (input: { uuid: string }) => {
   // ...
 };
 ```
+
+## companions
+
+### `asFrozenDeep`
+
+the `asFrozenDeep` function freezes a value and every value it reaches, in place, and returns it typed as `FrozenDeep<T>`. a write the type refuses also throws at runtime.
+
+```ts
+import { asFrozenDeep } from 'type-fns';
+
+const event = asFrozenDeep({ page: { limit: 10 }, seen: new Map([['sms', 1]]) });
+event.page.limit = 50;    // 🛑 typescript error; at runtime, a TypeError
+event.seen.set('push', 2); // 🛑 typescript error; at runtime, a ConstraintError (a bare Object.freeze permits it)
+```
+
+it returns the same reference, so any other holder of a sub-object sees it frozen too. it reaches non-enumerable props as well, so `new Error('x', { cause })` freezes `cause`, yet never enters a function's `prototype`, which every instance of a class shares. it is safe on cycles and shared sub-objects, and a second call is a no-op. it checks the whole value before it freezes any of it, so a refusal (a typed array with elements, a global or sticky `RegExp`, or a map sealed by a bare `Object.freeze`) leaves the value untouched. each refusal is a `ConstraintError` that names where the refused object sits and how to fix it:
+
+```
+✋ ConstraintError: asFrozenDeep can not freeze a typed array with elements
+
+{
+  "path": "value.event.records[1].raw",
+  "kind": "Uint8Array",
+  "byteLength": 1,
+  "hint": "convert it to a plain array first, e.g. Array.from(bytes)"
+}
+```
+
+a bare `Object.freeze` lets a built-in change its internal state through its own methods. `asFrozenDeep` refuses those at runtime: `Map` and `Set` (`set`, `add`, `delete`, `clear`), `WeakMap` and `WeakSet` (`set`, `add`, `delete`), `Date` and `DataView` (every `set*`), `RegExp` (`compile`), and `ArrayBuffer` (`resize`, `transfer`). the type keeps the object arm for all but `Map` and `Set`, so those calls still compile.
+
+what it does not reach: the bytes of an `ArrayBuffer` through a view built on it, a class instance's `#private` fields through its own methods, the value a getter returns (it never invokes a getter), and a refused mutator called through its prototype, as in `Map.prototype.set.call(frozen, k, v)`.
+
+to change a frozen value, copy it and change the copy: `{ ...event, page: { ...event.page, limit: 50 } }`, or `new Map(event.seen)` for a map.