@oazmi/superbuild 0.1.0

package/esm/deps/jsr.io/@oazmi/kitchensink/0.10.0/src/struct.d.ts

@@ -0,0 +1,734 @@
+/** utility functions for common object structures and `Object` manipulation.
+ *
+ * @module
+*/
+import type { ConstructorOf, PrototypeOf } from "./typedefs.js";
+/** represents a 2d rectangle. compatible with {@link DOMRect}, without its inherited annoying readonly fields. */
+export interface Rect {
+    x: number;
+    y: number;
+    width: number;
+    height: number;
+}
+/** represents an `ImageData` with optional color space information. */
+export interface SimpleImageData extends Omit<ImageData, "colorSpace" | "data"> {
+    data: Uint8ClampedArray | Uint8Array;
+    colorSpace?: PredefinedColorSpace;
+}
+/** get an equivalent rectangle where the `height` and `width` are positive.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * const
+ * 	my_rect: Rect = { x: -20, y: 100, width: 50, height: -30 },
+ * 	my_abs_rect = positiveRect(my_rect)
+ *
+ * assertEquals(my_abs_rect, {
+ * 	x: -20,
+ * 	y: 70,
+ * 	width: 50,
+ * 	height: 30,
+ * })
+ * ```
+*/
+export declare const positiveRect: (r: Rect) => Rect;
+/** get the constructor of a class's instance.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * class K { constructor(public value: any) { } }
+ *
+ * const a = new K(1)
+ * const b = new (constructorOf(a))(2) // equivalent to `const b = new K(2)`
+ *
+ * a satisfies K
+ * b satisfies K
+ * assertEquals(a !== b, true)
+ * ```
+*/
+export declare const constructorOf: <T, Args extends any[] = any[]>(class_instance: T) => ConstructorOf<T, Args>;
+/** use the constructor of a class's instance to construct a new instance.
+ *
+ * this is useful for avoiding pollution of code with `new` keyword along with some wonky placement of braces to make your code work.
+ *
+ * @example
+ * ```ts
+ * class K {
+ * 	value: number
+ *
+ * 	constructor(value1: number, value2: number) {
+ * 		this.value = value1 + value2
+ * 	}
+ * }
+ *
+ * const a = new K(1, 1)
+ * const b = constructFrom(a, 2, 2) // equivalent to `const b = new K(2, 2)`
+ *
+ * // vanilla way of constructing `const c = new K(3, 3)` using `a`
+ * const c = new (Object.getPrototypeOf(a).constructor)(3, 3)
+ *
+ * a satisfies K
+ * b satisfies K
+ * c satisfies K
+ * ```
+*/
+export declare const constructFrom: <T, Args extends any[] = any[]>(class_instance: T, ...args: Args) => T;
+/** get the prototype object of a class.
+ *
+ * this is useful when you want to access bound-methods of an instance of a class, such as the ones declared as:
+ *
+ * ```ts ignore
+ * class X {
+ * 	methodOfProto() { }
+ * }
+ * ```
+ *
+ * these bound methods are not available via destructure of an instance, because they then lose their `this` context.
+ * the only functions that can be destructured without losing their `this` context are the ones declared via assignment:
+ *
+ * ```ts ignore
+ * class X {
+ * 	fn = () => { }
+ * 	fn2 = function () { }
+ * }
+ * ```
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * const
+ * 	array_proto = prototypeOfClass(Array<number>),
+ * 	arr = [1, 2, 3, 4, 5]
+ *
+ * array_proto.push.call(arr, 6)
+ * assertEquals(arr, [1, 2, 3, 4, 5, 6])
+ *
+ * const slow_push_to_arr = (...values: number[]) => (arr.push(...values))
+ * // the following declaration is more performant than `slow_push_to_arr`,
+ * // and it also has lower memory footprint.
+ * const fast_push_to_arr = array_proto.push.bind(arr)
+ *
+ * slow_push_to_arr(7, 8)  // sloww & bigg
+ * fast_push_to_arr(9, 10) // quicc & smol
+ * assertEquals(arr, [1, 2, 3, 4, 5, 6, 7, 8, 9, 10])
+ * ```
+*/
+export declare const prototypeOfClass: <T, Args extends any[] = any[]>(cls: ConstructorOf<T, Args>) => PrototypeOf<typeof cls>;
+/** configuration options for slicing the prototype chain returned by {@link prototypeChainOfObject}.
+ *
+ * only the following combination of options are supported:
+ * - `start` and `end`
+ * - `start` and `delta`
+ * - `end` and `delta`
+ *
+ * if all three options are defined, then the `delta` option will be ignored.
+*/
+export interface PrototypeChainOfObjectConfig {
+    /** the inclusive starting depth of the returned prototype chain. defaults to `0`.
+     *
+     * it can be one of the following:
+     * - a positive integer: slices the full prototype chain starting from the given index.
+     * - a negative integer: slices the full prototype chain starting from the end of the sequence.
+     * - an object: slices the full prototype chain starting from the point where the given object is found (inclusive).
+     *   if the object is not found then the `start` option will be treated as `0` (i.e. starting from beginning of the chain array).
+    */
+    start?: number | Object;
+    /** the exclusive ending depth of the returned prototype chain. defaults to `-1`.
+     *
+     * it can be one of the following:
+     * - a positive integer: slices the full prototype chain ending at the given index.
+     * - a negative integer: slices the full prototype chain from the end of the sequence.
+     * - an object or `null`: slices the full prototype chain ending at the point where the given object is found (exclusive).
+     *   if the object is not found then the `end` option will be treated as `-1` (i.e. ending at the end of the chain array).
+    */
+    end?: number | Object | null;
+    /** the additional depth to traverse on top of either {@link start} or {@link end}.
+     * make sure that you always provide a positive number.
+     *
+     * - when the `start` option is specified, you will be given `delta` number of prototype elements after the starting point.
+     * - when the `end` option is specified, you will be given `delta` number of prototype elements before the ending point.
+    */
+    delta?: number;
+}
+/** get the prototype chain of an object, with optional slicing options.
+ *
+ * @param obj the object whose prototype chain is to be found.
+ * @param config optional configuration for slicing the full prototype chain.
+ * @returns the sliced prototype chain of the given object.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals, assertThrows } from "jsr:@std/assert"
+ *
+ * // aliasing our functions for brevity
+ * const
+ * 	fn = prototypeChainOfObject,
+ * 	eq = assertEquals
+ *
+ * class A extends Array { }
+ * class B extends A { }
+ * class C extends B { }
+ * class D extends C { }
+ *
+ * const
+ * 	a = new A(0),
+ * 	b = new B(0),
+ * 	c = new C(0),
+ * 	d = new D(0)
+ *
+ * eq(fn(d), [D.prototype, C.prototype, B.prototype, A.prototype, Array.prototype, Object.prototype, null])
+ * eq(fn(b), [B.prototype, A.prototype, Array.prototype, Object.prototype, null])
+ *
+ * // slicing the prototype chain, starting from index 2 till the end
+ * eq(fn(d, { start: 2 }), [B.prototype, A.prototype, Array.prototype, Object.prototype, null])
+ *
+ * // slicing using a negative index
+ * eq(fn(d, { start: -2 }), [Object.prototype, null])
+ *
+ * // slicing using an object
+ * eq(fn(d, { start: B.prototype }), [B.prototype, A.prototype, Array.prototype, Object.prototype, null])
+ *
+ * // when the slicing object is not found, the start index will be assumed to be `0` (default value)
+ * eq(fn(d, { start: Set.prototype }), [D.prototype, C.prototype, B.prototype, A.prototype, Array.prototype, Object.prototype, null])
+ *
+ * // slicing between the `start` index (inclusive) and the end index
+ * eq(fn(d, { start: 2, end:    6 }), [B.prototype, A.prototype, Array.prototype, Object.prototype])
+ * eq(fn(d, { start: 2, end:   -1 }), [B.prototype, A.prototype, Array.prototype, Object.prototype])
+ * eq(fn(d, { start: 2, end: null }), [B.prototype, A.prototype, Array.prototype, Object.prototype])
+ *
+ * // if the end index is not found, the slicing will occur till the end
+ * eq(fn(d, { end: Set.prototype}), [D.prototype, C.prototype, B.prototype, A.prototype, Array.prototype, Object.prototype, null])
+ *
+ * // slicing using a `delta` argument will let you define how many elements you wish to:
+ * // - traverse forward from the `start` index
+ * // - traverse backwards from the `end` index
+ * eq(fn(d, { start:  2, delta: 3 }), [B.prototype, A.prototype, Array.prototype])
+ * eq(fn(d, { end:   -2, delta: 2 }), [A.prototype, Array.prototype])
+ * eq(fn(d, { end: null, delta: 4 }), [B.prototype, A.prototype, Array.prototype, Object.prototype])
+ *
+ * eq(fn(d,  { start: 1, delta: 1 }), fn(c,  { start: 0, delta: 1 }))
+ * eq(fn(c,  { start: 1, delta: 1 }), fn(b,  { start: 0, delta: 1 }))
+ * eq(fn(b,  { start: 1, delta: 1 }), fn(a,  { start: 0, delta: 1 }))
+ * eq(fn(a,  { start: 1, delta: 1 }), fn([], { start: 0, delta: 1 }))
+ * eq(fn([], { start: 1, delta: 1 }), fn({}, { start: 0, delta: 1 }))
+ *
+ * // you may also traverse through the inheritance chain of a class, but it will be a good idea to set your `end` point to `Function.prototype`,
+ * // since all class objects are effectively functions (i.e. their common ancestral prototype if `Function.prototype`).
+ * eq(fn(D, { start: 0, end: Function.prototype }), [C, B, A, Array])
+ * eq(fn(D), [C, B, A, Array, Function.prototype, Object.prototype, null])
+ * eq(fn(class {}), [Function.prototype, Object.prototype, null])
+ * eq(fn(class extends Object {}), [Object, Function.prototype, Object.prototype, null])
+ * eq(fn(class extends Map {}), [Map, Function.prototype, Object.prototype, null])
+ *
+ * // you cannot acquire the prototype chain of the `null` object
+ * assertThrows(() => { fn(null) })
+ * ```
+*/
+export declare function prototypeChainOfObject(obj: any, config?: PrototypeChainOfObjectConfig): object[];
+/** get an object's list of **owned** keys (string keys and symbol keys).
+ *
+ * > [!note]
+ * > **owned** keys of an object are not the same as just _any_ key of the object.
+ * > an owned key is one that it **directly** owned by the object, not owned through inheritance, such as the class methods.
+ * > more precisely, in javascript, which ever member of an object that we call a _property_, is an **owned** key.
+ *
+ * if you wish to acquire **all remaining** inherited keys of an object, you will want use {@link getInheritedPropertyKeys}.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * const
+ * 	symbol_h = Symbol("symbol h"),
+ * 	symbol_i = Symbol("symbol i"),
+ * 	symbol_j = Symbol("symbol j")
+ *
+ * class A {
+ * 	a = { v: 1 }
+ * 	b = { v: 2 }
+ * 	c: { v: number }
+ * 	d() { return { v: 4 } }
+ * 	e() { return { v: 5 } }
+ * 	f = () => { return { v: 6 } }
+ * 	g: () => ({ v: number })
+ * 	[symbol_h]() { return { v: 8 } }
+ * 	[symbol_i] = () => { return { v: 9 } }
+ *
+ * 	constructor() {
+ * 		this.c = { v: 3 }
+ * 		this.g = () => { return { v: 7 } }
+ * 	}
+ * }
+ *
+ * class B extends A {
+ * 	override a = { v: 11 }
+ * 	override e() { return { v: 15 } }
+ * 	//@ts-ignore: typescript does not permit defining a method over the name of an existing property
+ * 	override g() { return { v: 17 } }
+ * 	[symbol_j] = () => { return { v: 20 } }
+ *
+ * 	constructor() { super() }
+ * }
+ *
+ * const
+ * 	a = new A(),
+ * 	b = new B()
+ *
+ * assertEquals(b.a, { v: 11 })
+ * assertEquals(b.b, { v: 2 })
+ * assertEquals(b.c, { v: 3 })
+ * assertEquals(b.d(), { v: 4 })
+ * assertEquals(b.e(), { v: 15 })
+ * assertEquals(b.f(), { v: 6 })
+ * assertEquals(b.g(), { v: 7 }) // notice that the overridden method is not called, and the property is called instead
+ * assertEquals(Object.getPrototypeOf(b).g(), { v: 17 })
+ * assertEquals(b[symbol_h](), { v: 8 })
+ * assertEquals(b[symbol_i](), { v: 9 })
+ * assertEquals(b[symbol_j](), { v: 20 })
+ *
+ * assertEquals(
+ * 	new Set(getOwnPropertyKeys(a)),
+ * 	new Set(["a", "b", "c", "f", "g", symbol_i]),
+ * )
+ * assertEquals(
+ * 	new Set(getOwnPropertyKeys(Object.getPrototypeOf(a))),
+ * 	new Set(["constructor", "d", "e", symbol_h]),
+ * )
+ * assertEquals(
+ * 	new Set(getOwnPropertyKeys(b)),
+ * 	new Set(["a", "b", "c", "f", "g", symbol_i, symbol_j]),
+ * )
+ * assertEquals(
+ * 	new Set(getOwnPropertyKeys(Object.getPrototypeOf(b))),
+ * 	new Set(["constructor", "e", "g"]),
+ * )
+ * ```
+*/
+export declare const getOwnPropertyKeys: <T extends object>(obj: T) => (keyof T)[];
+/** get all **inherited** list of keys (string keys and symbol keys) of an object, up till a certain `depth`.
+ *
+ * directly owned keys will not be returned.
+ * for that, you should use the {@link getOwnPropertyKeys} function.
+ *
+ * the optional `depth` parameter lets you control how deep you'd like to go collecting the inherited keys.
+ *
+ * @param obj the object whose inherited keys are to be listed.
+ * @param depth the inheritance depth until which the function will accumulate keys for.
+ *   - if an object `A` is provided as the `depth`,
+ *     then all inherited keys up until `A` is reached in the inheritance chain will be collected, but not including the keys of `A`.
+ *   - if a number `N` is provided as the `depth`,
+ *     then the function will collect keys from `N` number of prototypes up the inheritance chain.
+ *     - a depth of `0` would imply no traversal.
+ *     - a depth of `1` would only traverse the first direct prototype of `obj` (i.e. `getOwnPropertyKeys(Object.getPrototypeOf(obj))`).
+ *   @defaultValue `Object.prototype`
+ * @returns an array of keys that the object has inherited (string or symbolic keys).
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * const
+ * 	symbol_h = Symbol("symbol h"),
+ * 	symbol_i = Symbol("symbol i"),
+ * 	symbol_j = Symbol("symbol j")
+ *
+ * class A {
+ * 	a = { v: 1 }
+ * 	b = { v: 2 }
+ * 	c: { v: number }
+ * 	d() { return { v: 4 } }
+ * 	e() { return { v: 5 } }
+ * 	f = () => { return { v: 6 } }
+ * 	g: () => ({ v: number })
+ * 	[symbol_h]() { return { v: 8 } }
+ * 	[symbol_i] = () => { return { v: 9 } }
+ *
+ * 	constructor() {
+ * 		this.c = { v: 3 }
+ * 		this.g = () => { return { v: 7 } }
+ * 	}
+ * }
+ *
+ * class B extends A {
+ * 	override a = { v: 11 }
+ * 	override e() { return { v: 15 } }
+ * 	//@ts-ignore: typescript does not permit defining a method over the name of an existing property
+ * 	override g() { return { v: 17 } }
+ * 	[symbol_j] = () => { return { v: 20 } }
+ *
+ * 	constructor() { super() }
+ * }
+ *
+ * const
+ * 	a = new A(),
+ * 	b = new B()
+ *
+ * assertEquals(
+ * 	new Set(getInheritedPropertyKeys(a)),
+ * 	new Set(["constructor", "d", "e", symbol_h]),
+ * )
+ *
+ * // below, notice how the inherited keys of `a` equal to its prototype's owned keys.
+ * // this is because methods of instances of `A` are defined on the prototype (i.e. properties of the prototype, rather than the instances').
+ * assertEquals(
+ * 	new Set(getInheritedPropertyKeys(a)),
+ * 	new Set(getOwnPropertyKeys(A.prototype)),
+ * )
+ *
+ * // also notice that inherited keys of `A.prototype` comes out as empty here,
+ * // even though it does techinally inherit members from its own prototype (which is `Object.prototype`).
+ * // the reason is that by default, we do not go deeper than `Object.prototype` to look for more keys.
+ * // this is because from an end-user's perspective, those keys are not useful.
+ * assertEquals(
+ * 	getInheritedPropertyKeys(A.prototype),
+ * 	[],
+ * )
+ *
+ * assertEquals(
+ * 	new Set(getInheritedPropertyKeys(b)),
+ * 	new Set(["constructor", "e", "g", "d", symbol_h]),
+ * )
+ * assertEquals(
+ * 	new Set(getInheritedPropertyKeys(b)),
+ * 	new Set([
+ * 		...getOwnPropertyKeys(B.prototype),
+ * 		...getInheritedPropertyKeys(B.prototype),
+ * 	]),
+ * )
+ * assertEquals(
+ * 	new Set(getInheritedPropertyKeys(B.prototype)),
+ * 	new Set(["constructor", "e", "d", symbol_h]),
+ * )
+ *
+ * // testing out various depth
+ * assertEquals(
+ * 	new Set(getInheritedPropertyKeys(a, 1)),
+ * 	new Set(getOwnPropertyKeys(A.prototype)),
+ * )
+ * assertEquals(
+ * 	new Set(getInheritedPropertyKeys(b, 1)),
+ * 	new Set(getOwnPropertyKeys(B.prototype)),
+ * )
+ * assertEquals(
+ * 	new Set(getInheritedPropertyKeys(b, A.prototype)),
+ * 	new Set(getOwnPropertyKeys(B.prototype)),
+ * )
+ * assertEquals(
+ * 	new Set(getInheritedPropertyKeys(b, 2)),
+ * 	new Set([
+ * 		...getOwnPropertyKeys(B.prototype),
+ * 		...getOwnPropertyKeys(A.prototype),
+ * 	]),
+ * )
+ * // below, we collect all inherited keys of `b`, including those that come from `Object.prototype`,
+ * // which is the base ancestral prototype of all objects.
+ * // to do that, we set the `depth` to `null`, which is the prototype of `Object.prototype`.
+ * // the test below may fail in new versions of javascript, where
+ * assertEquals(
+ * 	new Set(getInheritedPropertyKeys(b, null)),
+ * 	new Set([
+ * 		"constructor", "e", "g", "d", symbol_h,
+ * 		"__defineGetter__", "__defineSetter__", "hasOwnProperty", "__lookupGetter__", "__lookupSetter__",
+ * 		"isPrototypeOf", "propertyIsEnumerable", "toString", "valueOf", "toLocaleString",
+ * 	]),
+ * )
+ * ```
+*/
+export declare const getInheritedPropertyKeys: <T extends object>(obj: T, depth?: (number | Object | null)) => (keyof T)[];
+/** get all **owned** getter property keys of an object `obj` (string keys and symbol keys).
+ *
+ * TODO: in the future, consider creating a `getInheritedGetterKeys` function with the same signature as `getInheritedPropertyKeys`.
+ *
+ * > [!note]
+ * > inherited getter property keys will not be included.
+ * > only directly defined getter property keys (aka owned keys) will be listed.
+*/
+export declare const getOwnGetterKeys: <T extends object>(obj: T) => (keyof T)[];
+/** get all **owned** setter property keys of an object `obj` (string keys and symbol keys).
+ *
+ * TODO: in the future, consider creating a `getInheritedSetterKeys` function with the same signature as `getInheritedPropertyKeys`.
+ *
+ * > [!note]
+ * > inherited setter property keys will not be included.
+ * > only directly defined setter property keys (aka owned keys) will be listed.
+*/
+export declare const getOwnSetterKeys: <T extends object>(obj: T) => (keyof T)[];
+/** a utility type that mirrors a type `T`, in addition to enclosing the object `T` under the composition property key `P`.
+ *
+ * this utility type is used by the functions {@link mirrorObjectThroughComposition} and {@link subclassThroughComposition}.
+ *
+ * @example
+ * ```ts
+ * const obj_a = {
+ * 	hello: "world",
+ * 	goodbye: "earth",
+ * 	answer() { return 42 },
+ * }
+ *
+ * const obj_b = {
+ * 	_super: obj_a, // composing/enclosing `obj_a`
+ * 	...obj_a,      // mirroring the methods and properties of `obj_a`
+ * }
+ *
+ * obj_b satisfies MirrorComposition<typeof obj_a, "_super">
+ * ```
+*/
+export type MirrorComposition<T, P extends PropertyKey> = (T & {
+    [composition_key in P]: T;
+});
+/** configuration options for the function {@link mirrorObjectThroughComposition}. */
+export interface MirrorObjectThroughCompositionConfig<P extends PropertyKey = string> {
+    /** the key to use to access the composed base object. */
+    baseKey: P;
+    /** specify whether or not the given object's prototype methods and properties should also be mimicked/mirrored.
+     *
+     * for fine-grained control of _which_ prototypes from the full prototype chain get mimicked, you can provide one of the following configuration objects:
+     * - `Array<Object>`: a manually assembled array of prototype objects, starting with immediate prototype of `obj`, and ending with the last ancestral prototype object.
+     * - {@link PrototypeChainOfObjectConfig | `PrototypeChainOfObjectConfig`}: a description object for a slice of continuous prototype chain, used by the function {@link prototypeChainOfObject}.
+     * - `true`: equivalent to the {@link PrototypeChainOfObjectConfig | prototype slice description} `{ start: 0, end: Object.prototype }`.
+     * - `false`: equivalent to the manually assembled prototype chain `[]` (empty array).
+     *
+     * @defaultValue `true`
+    */
+    mirrorPrototype?: boolean | PrototypeChainOfObjectConfig | Array<Object>;
+    /** specify additional property keys that should be mirrored.
+     *
+     * this would be needed in situations where not all property keys of the given `obj` are immediately discoverable via `Object.getOwnPropertyNames` and `Object.getOwnPropertySymbols`.
+     * for instance, dynamically assigned property keys, and class-instance bound keys cannot be deduced beforehand.
+     * and so, for such cases, you will need to address those non-discoverable keys in this config option, should you wish for them to be mirrored later on.
+     *
+     * @defaultValue `[]` (empty array)
+    */
+    propertyKeys?: Iterable<PropertyKey>;
+    /** specify a set of keys that should **not** be mirrored.
+     *
+     * @defaultValue `[]` (empty array)
+    */
+    ignoreKeys?: Iterable<PropertyKey>;
+    /** specify an optional existing target object on which the provided `obj` gets mirrored onto.
+     *
+     * if none is specified, then a new empty object is used as the target.
+     * if a target object is provided, then the same object will be returned by the {@link mirrorObjectThroughComposition} function.
+     *
+     * @defaultValue `{}` (new empty object)
+    */
+    target?: object;
+}
+/** create a new object that mirrors that functionality of an existing object `obj`, through composition.
+ *
+ * @param obj the object that is to be mimicked and composed.
+ * @param config control how the mirroring composition should behave.
+ *   refer to the docs of {@link MirrorObjectThroughCompositionConfig} for more details.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * type TypeofB = Array<number> & { getLength(): number }
+ * type TypeofC = TypeofB & { countZeros(): number }
+ *
+ * const a = Array.prototype
+ * const b = {
+ * 	getLength(): number { return this.length }
+ * } as TypeofB
+ * const c = {
+ * 	countZeros(): number { return [...this].filter((value) => (value === 0)).length }
+ * } as TypeofC
+ *
+ * Object.setPrototypeOf(b, a)
+ * Object.setPrototypeOf(c, b)
+ *
+ * // below, we create an object `d` that mirrors the methods and protperties of `c`, but does not actually inherit it.
+ * const d = mirrorObjectThroughComposition(c, {
+ * 	baseKey: "_super",
+ * 	propertyKeys: ["length"],
+ * })
+ *
+ * // notice that `d` does not inherit `c` as its prototype, despite being able to utilize its methods and properties.
+ * assertEquals(Object.getPrototypeOf(d), Object.prototype, "`d` does not inherit `c`")
+ *
+ * d.push(0, 0, 0, 0, 1)
+ * assertEquals([...d], [0, 0, 0, 0, 1], "`d` also mirrors symbolic keys (such as iterators)")
+ * assertEquals([...c], [0, 0, 0, 0, 1], "mutations made to `d` are applied to `c`")
+ * assertEquals(d._super, c, "`c` is accessible via the `baseKey` (\"_super\") property")
+ * assertEquals(d.length, 5)
+ * assertEquals(c.length, 5)
+ * assertEquals(d.getLength(), 5)
+ * assertEquals(d.countZeros(), 4)
+ * d.splice(0, 3)
+ * assertEquals(d.countZeros(), 1)
+ * assertEquals(c.countZeros(), 1)
+ *
+ * // you may even hot-swap the object that is being composed inside of `d`.
+ * const e = [1, 2, 3, 4, 5, 6, 7, 8, 9]
+ * Object.setPrototypeOf(e, c)
+ * d._super = e as TypeofC
+ * assertEquals(d.length, 9)
+ * assertEquals(d.getLength(), 9)
+ * assertEquals(d.countZeros(), 0)
+ *
+ * // it is also possible for you to provide an existing `target` object onto which the mirroring should occur.
+ * // moreover, you can ignore specific keys which you would like not to be mirrored using the `ignoreKeys` option.
+ * class F {
+ * 	methodF() { return "press f for your fallen comrades" }
+ * 	// to stop typescript from complaining, we declare the instance methods and properties that will be mirrored.
+ * 	declare _super: typeof c
+ * 	declare length: number
+ * 	declare getLength: undefined
+ * 	declare countZeros: () => number
+ * }
+ * mirrorObjectThroughComposition(c, {
+ * 	target: F.prototype,
+ * 	baseKey: "_super",
+ * 	propertyKeys: ["length"],
+ * 	ignoreKeys: ["getLength"],
+ * })
+ * const f = new F()
+ * assertEquals(f instanceof F, true)
+ * assertEquals(f._super, c)
+ * assertEquals(f.length, 2)
+ * assertEquals(f.countZeros(), 1)
+ * assertEquals(f.getLength, undefined) // the `getLength` is not mirrored because it was present in the `ignoreKeys` option
+ * assertEquals(f.methodF(), "press f for your fallen comrades")
+ * ```
+*/
+export declare const mirrorObjectThroughComposition: <T, P extends PropertyKey>(obj: T, config: MirrorObjectThroughCompositionConfig<P>) => MirrorComposition<T, P>;
+/** configuration options for the function {@link subclassThroughComposition}.
+ *
+ * this configuration effectively specifies the {@link MirrorObjectThroughCompositionConfig} configuration for the `class` and its `instance`s.
+ *
+ * by default, the following subconfiguration is used for both `class` and `instance`:
+ * `{ baseKey: "_super", mirrorPrototype: true, propertyKeys: [] }`
+ *
+ * - if your class's instances contain properties that are not defined in the prototype (i.e. dynamically assigned properties),
+ *   then you will need to define them in {@link MirrorObjectThroughCompositionConfig.propertyKeys | `instance.propertyKeys`}.
+ *   in a similar way, if your class has dynamically assigned static properties, then you'll need to define them in
+ *   {@link MirrorObjectThroughCompositionConfig.propertyKeys | `class.propertyKeys`} for them to get mirrored.
+ *
+ * - the `baseKey` option lets you pick the key that is used for accessing the composed base object from the derived subclass.
+ *   assuming that `class.baseKey = "_super"` and `instance.baseKey = "_super"`, then the generated "subclass" will be able to access the enclosed class in the following way:
+ *   - inside a static class method: `this._super satisfies typeof cls`
+ *   - inside an instance method: `this._super satisfies InstanceType<typeof cls>`
+*/
+export interface SubclassThroughCompositionConfig<CLASS_KEY extends PropertyKey = string, INSTANCE_KEY extends PropertyKey = string> {
+    class?: Partial<Omit<MirrorObjectThroughCompositionConfig<CLASS_KEY>, "target">>;
+    instance?: Partial<Omit<MirrorObjectThroughCompositionConfig<INSTANCE_KEY>, "target">>;
+}
+/** a utility type for the return type of {@link subclassThroughComposition}. */
+export type MirrorCompositionClass<CLS extends ConstructorOf<any, any>, CLASS_KEY extends PropertyKey, INSTANCE_KEY extends PropertyKey> = CLS extends (new (...args: any[]) => infer T) ? MirrorComposition<CLS, CLASS_KEY> & {
+    new (...args: any[]): MirrorComposition<T, INSTANCE_KEY>;
+} : MirrorComposition<CLS, CLASS_KEY>;
+/** create a subclass of the given `cls` class through composition rather than ES6 inheritance (aka `extends`).
+ * the composed instance resides under the property `this._super`, and all instance methods of the super class are copied/mirrored in the output class.
+ *
+ * TODO: provide a motivation/justification when compositional-mirroring subclass might be necessary to use instead of ES6 `extends` inheritance.
+ *
+ * @param cls the class to subclass through composition.
+ * @param property_keys specify additional property keys that exist within the instance of the class that need to be mirrored.
+ * @returns a class whose instances fully mirror the provided `cls` class's instance, without actually inheriting it.
+ *
+ * @example
+ * ```ts
+ * import { assertEquals } from "jsr:@std/assert"
+ *
+ * class A<T> extends Array<T> { constructor(quantity: number) { super(quantity) } }
+ * class B<T> extends subclassThroughComposition(A, {
+ * 	class: {},
+ * 	instance: { propertyKeys: ["length"] },
+ * })<T> { }
+ *
+ * // `B` mirrors the constructor of `A`, as well as provide an additional `"_super"` property to access the enclosed (class which is `A`)
+ * B satisfies { new(amount: number): B<any> }
+ * B._super satisfies typeof A
+ * // the following cannot be satisfied due to `A`'s restrictive constructor: `B satisfies { new(item1: string, item2: string, item3: string): B<string> }`
+ * // even though `A`'s super class (`Array`) does permit that kind of constructor signature:
+ * Array satisfies { new(item1: string, item2: string, item3: string): Array<string> }
+ *
+ * const my_array = new B<number>(5)
+ *
+ * // `my_array` encloses an instance of its "subclass" (which is an instance of class `A`) under the `"_super"` key.
+ * assertEquals(my_array instanceof B, true)
+ * assertEquals(my_array._super instanceof A, true)
+ * my_array._super satisfies A<unknown> // this should have been narrowed to `satisfies A<number>`, but typing class extensions with generics is nearly impossible
+ *
+ * // `my_array` mirrors the properties and methods of the instances of the "subclass" that it encloses.
+ * my_array.fill(1)
+ * my_array.push(2)
+ * my_array.push(3)
+ * assertEquals(my_array.at(-1), 3)
+ * assertEquals(my_array._super.at(-1), 3)
+ * assertEquals(my_array.length, 7)
+ * assertEquals(my_array._super.length, 7)
+ *
+ * // `my_array` mirrors the symbolic properties and methods as well.
+ * assertEquals([...my_array], [1, 1, 1, 1, 1, 2, 3]) // the `Symbol.iterator` method is mirrored successfully
+ *
+ * // `my_array` when a method that returns `new this.constructor(...)` (such as `Array.prototype.splice`), then an instance of
+ * // the enclosed subclass `A` will be created instead of `B` (had we had a regular inheritance via `class B extends A { }`).
+ * const
+ * 	splice_of_my_array = my_array.splice(0, 4, 0, 0),
+ * 	slice_of_my_array = my_array.slice(3, 4)
+ * assertEquals(splice_of_my_array instanceof A, true)
+ * assertEquals(slice_of_my_array instanceof A, true)
+ * assertEquals([...splice_of_my_array], [1, 1, 1, 1])
+ * assertEquals([...slice_of_my_array], [2])
+ * assertEquals([...my_array], [0, 0, 1, 2, 3])
+ * assertEquals([...my_array._super], [0, 0, 1, 2, 3])
+ *
+ * // the class `B` also mirrors static properties and static methods of `A` (and its inherited ones).
+ * // this means that any static method that creates a new instance via `new this(...)` will create an instance of `A` instead of `B`.
+ * const
+ * 	new_array_1 = B.from(["hello", "world"]),
+ * 	new_array_2 = B.of("goodbye", "world")
+ * assertEquals(new_array_1 instanceof A, true)
+ * assertEquals(new_array_2 instanceof A, true)
+ * assertEquals(new_array_1, A.from(["hello", "world"]))
+ * assertEquals(new_array_2, A.of("goodbye", "world"))
+ * ```
+*/
+export declare const subclassThroughComposition: <CLS extends ConstructorOf<any, any>, CLASS_KEY extends PropertyKey = "_super", INSTANCE_KEY extends PropertyKey = "_super">(cls: CLS, config?: SubclassThroughCompositionConfig<CLASS_KEY, INSTANCE_KEY>) => MirrorCompositionClass<CLS, CLASS_KEY, INSTANCE_KEY>;
+/** monkey patch the prototype of a class.
+ *
+ * TODO: give usage examples and situations where this will be useful.
+*/
+export declare const monkeyPatchPrototypeOfClass: <T, Args extends any[] = any[]>(cls: ConstructorOf<T, Args>, key: keyof T, value: T[typeof key]) => void;
+/** type definition of a primitive javascript object. */
+export type PrimitiveObject = string | number | bigint | boolean | symbol | undefined;
+/** type definition of a non-primitive javascript object. */
+export type ComplexObject = object | Function;
+/** check if `obj` is either an object or function. */
+export declare const isComplex: (obj: any) => obj is ComplexObject;
+/** check if `obj` is neither an object nor a function. */
+export declare const isPrimitive: (obj: any) => obj is PrimitiveObject;
+/** check if `obj` is a `function`.
+ *
+ * TODO: consider if it would be a good idea to include a generic parameter for the function's signature.
+ * i.e.: `<FN extends Function = Function>(obj: any): obj is FN`
+*/
+export declare const isFunction: (obj: any) => obj is Function;
+/** check if `obj` is an `Object`. */
+export declare const isObject: <T extends object = object>(obj: any) => obj is T;
+/** check if `obj` is an `Array`. */
+export declare const isArray: (<T = any>(obj: any) => obj is Array<T>);
+/** check if `obj` is a `Record`, which is any non-nullable object that isn't an array;
+ * kind of like a dictionary.
+*/
+export declare const isRecord: <R extends Record<any, any> = any>(obj: any) => obj is R;
+/** check if `obj` is a `string`. */
+export declare const isString: (obj: any) => obj is string;
+/** check if `obj` is a `number`. */
+export declare const isNumber: (obj: any) => obj is number;
+/** check if `obj` is a `bigint`. */
+export declare const isBigint: (obj: any) => obj is bigint;
+/** check if `obj` is either a `number` or a `bigint`. */
+export declare const isNumeric: (obj: any) => obj is (number | bigint);
+/** check if `obj` is `boolean`. */
+export declare const isBoolean: (obj: any) => obj is boolean;
+/** check if `obj` is a `symbol`. */
+export declare const isSymbol: (obj: any) => obj is symbol;
+//# sourceMappingURL=struct.d.ts.map