@fluidframework/tree 2.0.0-dev-rc.1.0.0.224419

package/dist/util/utils.js

@@ -0,0 +1,376 @@
+"use strict";
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.compareStrings = exports.capitalize = exports.disposeSymbol = exports.compareNamed = exports.oneFromSet = exports.invertMap = exports.transformObjectMap = exports.objectToMap = exports.generateStableId = exports.useAsyncDeterministicStableId = exports.useDeterministicStableId = exports.assertNonNegativeSafeInteger = exports.assertValidRange = exports.assertValidIndex = exports.assertValidRangeIndices = exports.isJsonObject = exports.JsonCompatibleReadOnlySchema = exports.zipIterables = exports.mapIterable = exports.getOrAddEmptyToMap = exports.getOrCreate = exports.compareSets = exports.makeArray = exports.isReadonlyArray = exports.fail = exports.clone = exports.asMutable = void 0;
+const core_utils_1 = require("@fluidframework/core-utils");
+const typebox_1 = require("@sinclair/typebox");
+const structured_clone_1 = __importDefault(require("@ungap/structured-clone"));
+const id_compressor_1 = require("@fluidframework/id-compressor");
+/**
+ * Casts a readonly object to a mutable one.
+ * Better than casting to `Mutable<Foo>` because it doesn't risk casting a non-`Foo` to a `Mutable<Foo>`.
+ * @param readonly - The object with readonly fields.
+ * @returns The same object but with a type that makes all fields mutable.
+ */
+function asMutable(readonly) {
+    return readonly;
+}
+exports.asMutable = asMutable;
+exports.clone = structured_clone_1.default;
+/**
+ * @internal
+ */
+function fail(message) {
+    throw new Error(message);
+}
+exports.fail = fail;
+/**
+ * Checks whether or not the given object is a `readonly` array.
+ *
+ * Note that this does NOT indicate if a given array should be treated as readonly.
+ * This instead indicates if an object is an Array, and is typed to tolerate the readonly case.
+ */
+function isReadonlyArray(x) {
+    // `Array.isArray()` does not properly narrow `readonly` array types by itself,
+    // so we wrap it in this type guard. This may become unnecessary if/when
+    // https://github.com/microsoft/TypeScript/issues/17002 is resolved.
+    return Array.isArray(x);
+}
+exports.isReadonlyArray = isReadonlyArray;
+/**
+ * Creates and populates a new array.
+ * @param size - The size of the array to be created.
+ * @param filler - Callback for populating the array with a value for a given index
+ */
+function makeArray(size, filler) {
+    const array = [];
+    for (let i = 0; i < size; ++i) {
+        array.push(filler(i));
+    }
+    return array;
+}
+exports.makeArray = makeArray;
+/**
+ * Compares two sets using callbacks.
+ * Early returns on first false comparison.
+ *
+ * @param a - One Set.
+ * @param b - The other Set.
+ * @param aExtra - Called for items in `a` but not `b`.
+ * @param bExtra - Called for items in `b` but not `a`.
+ * @param same - Called for items in `a` and `b`.
+ * @returns false iff any of the call backs returned false.
+ */
+function compareSets({ a, b, aExtra, bExtra, same, }) {
+    for (const item of a.keys()) {
+        if (!b.has(item)) {
+            if (aExtra && !aExtra(item)) {
+                return false;
+            }
+        }
+        else {
+            if (same && !same(item)) {
+                return false;
+            }
+        }
+    }
+    for (const item of b.keys()) {
+        if (!a.has(item)) {
+            if (bExtra && !bExtra(item)) {
+                return false;
+            }
+        }
+    }
+    return true;
+}
+exports.compareSets = compareSets;
+/**
+ * Retrieve a value from a map with the given key, or create a new entry if the key is not in the map.
+ * @param map - The map to query/update
+ * @param key - The key to lookup in the map
+ * @param defaultValue - a function which returns a default value. This is called and used to set an initial value for the given key in the map if none exists
+ * @returns either the existing value for the given key, or the newly-created value (the result of `defaultValue`)
+ */
+function getOrCreate(map, key, defaultValue) {
+    let value = map.get(key);
+    if (value === undefined) {
+        value = defaultValue(key);
+        map.set(key, value);
+    }
+    return value;
+}
+exports.getOrCreate = getOrCreate;
+/**
+ * Utility for dictionaries whose values are lists.
+ * Gets the list associated with the provided key, if it exists.
+ * Otherwise, creates an entry with an empty list, and returns that list.
+ */
+function getOrAddEmptyToMap(map, key) {
+    let collection = map.get(key);
+    if (collection === undefined) {
+        collection = [];
+        map.set(key, collection);
+    }
+    return collection;
+}
+exports.getOrAddEmptyToMap = getOrAddEmptyToMap;
+/**
+ * Map one iterable to another by transforming each element one at a time
+ * @param iterable - the iterable to transform
+ * @param map - the transformation function to run on each element of the iterable
+ * @returns a new iterable of elements which have been transformed by the `map` function
+ */
+function* mapIterable(iterable, map) {
+    for (const t of iterable) {
+        yield map(t);
+    }
+}
+exports.mapIterable = mapIterable;
+/**
+ * Returns an iterable of tuples containing pairs of elements from the given iterables
+ * @param iterableA - an iterable to zip together with `iterableB`
+ * @param iterableB - an iterable to zip together with `iterableA`
+ * @returns in iterable of tuples of elements zipped together from `iterableA` and `iterableB`.
+ * If the input iterables are of different lengths, then the extra elements in the longer will be ignored.
+ */
+function* zipIterables(iterableA, iterableB) {
+    const iteratorA = iterableA[Symbol.iterator]();
+    const iteratorB = iterableB[Symbol.iterator]();
+    for (let nextA = iteratorA.next(), nextB = iteratorB.next(); nextA.done !== true && nextB.done !== true; nextA = iteratorA.next(), nextB = iteratorB.next()) {
+        yield [nextA.value, nextB.value];
+    }
+}
+exports.zipIterables = zipIterables;
+/**
+ * @remarks TODO: Audit usage of this type in schemas, evaluating whether it is necessary and performance
+ * of alternatives.
+ *
+ * True "arbitrary serializable data" is probably fine, but some persisted types declarations might be better
+ * expressed using composition of schemas for runtime validation, even if we don't think making the types
+ * generic is worth the maintenance cost.
+ */
+exports.JsonCompatibleReadOnlySchema = typebox_1.Type.Any();
+/**
+ * Returns if a particular json compatible value is an object.
+ * Does not include `null` or arrays.
+ */
+function isJsonObject(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+exports.isJsonObject = isJsonObject;
+/**
+ * Verifies that the supplied indices are valid within the supplied array.
+ * @param startIndex - The starting index in the range. Must be in [0, length).
+ * @param endIndex - The ending index in the range. Must be within (start, length].
+ * @param array - The array the indices refer to
+ */
+function assertValidRangeIndices(startIndex, endIndex, array) {
+    (0, core_utils_1.assert)(endIndex >= startIndex, 0x79c /* Range indices are malformed. */);
+    assertValidIndex(startIndex, array, false);
+    assertValidIndex(endIndex, array, true);
+}
+exports.assertValidRangeIndices = assertValidRangeIndices;
+function assertValidIndex(index, array, allowOnePastEnd = false) {
+    assertNonNegativeSafeInteger(index);
+    if (allowOnePastEnd) {
+        (0, core_utils_1.assert)(index <= array.length, 0x378 /* index must be less than or equal to length */);
+    }
+    else {
+        (0, core_utils_1.assert)(index < array.length, 0x379 /* index must be less than length */);
+    }
+}
+exports.assertValidIndex = assertValidIndex;
+function assertValidRange({ start, end }, array) {
+    assertNonNegativeSafeInteger(start);
+    assertNonNegativeSafeInteger(end);
+    (0, core_utils_1.assert)(end <= array.length, 0x79d /* Range end must be less than or equal to length */);
+    (0, core_utils_1.assert)(start <= end, 0x79e /* Range start must be less than or equal to range start */);
+}
+exports.assertValidRange = assertValidRange;
+function assertNonNegativeSafeInteger(index) {
+    (0, core_utils_1.assert)(Number.isSafeInteger(index), 0x376 /* index must be an integer */);
+    (0, core_utils_1.assert)(index >= 0, 0x377 /* index must be non-negative */);
+}
+exports.assertNonNegativeSafeInteger = assertNonNegativeSafeInteger;
+/**
+ * The counter used to generate deterministic stable ids for testing purposes.
+ */
+let deterministicStableIdCount;
+/**
+ * Runs `f` with {@link generateStableId} altered to return sequential StableIds starting as a fixed seed.
+ * Used to make test logic that uses {@link generateStableId} deterministic.
+ *
+ * @remarks Only use this function for testing purposes.
+ *
+ * @example
+ *
+ * ```typescript
+ * function f() {
+ *    const id = generateStableId();
+ *    ...
+ * }
+ * const result = useDeterministicStableId(f());
+ * ```
+ */
+function useDeterministicStableId(f) {
+    (0, core_utils_1.assert)(deterministicStableIdCount === undefined, 0x6ce /* useDeterministicStableId cannot be nested */);
+    deterministicStableIdCount = 1;
+    try {
+        return f();
+        // Since this is intended to be used by tests, and test runners often recover from exceptions to run more tests,
+        // clean this up with a finally block to reduce risk of breaking unrelated tests after a failure.
+    }
+    finally {
+        deterministicStableIdCount = undefined;
+    }
+}
+exports.useDeterministicStableId = useDeterministicStableId;
+async function useAsyncDeterministicStableId(f) {
+    (0, core_utils_1.assert)(deterministicStableIdCount === undefined, 0x79f /* useAsyncDeterministicStableId cannot be nested */);
+    deterministicStableIdCount = 1;
+    try {
+        return await f();
+        // Since this is intended to be used by tests, and test runners often recover from exceptions to run more tests,
+        // clean this up with a finally block to reduce risk of breaking unrelated tests after a failure.
+    }
+    finally {
+        deterministicStableIdCount = undefined;
+    }
+}
+exports.useAsyncDeterministicStableId = useAsyncDeterministicStableId;
+/**
+ * Generates a random StableId.
+ *
+ * For test usage desiring deterministic results, see {@link useDeterministicStableId}.
+ */
+function generateStableId() {
+    if (deterministicStableIdCount !== undefined) {
+        (0, core_utils_1.assert)(deterministicStableIdCount < 281474976710656, 0x6cf /* The maximum valid value for deterministicStableIdCount is 16^12 */);
+        // Tried to generate a unique id prefixing it with the word 'beef'
+        return (0, id_compressor_1.assertIsStableId)(`beefbeef-beef-4000-8000-${(deterministicStableIdCount++)
+            .toString(16)
+            .padStart(12, "0")}`);
+    }
+    return (0, id_compressor_1.generateStableId)();
+}
+exports.generateStableId = generateStableId;
+/**
+ * Convert an object into a Map.
+ *
+ * This function must only be used with objects specifically intended to encode map like information.
+ * The only time such objects should be used is for encoding maps as object literals to allow for developer ergonomics or JSON compatibility.
+ * Even those two use-cases need to be carefully considered as using objects as maps can have a lot of issues
+ * (including but not limited to unintended access to __proto__ and other non-owned keys).
+ * This function helps these few cases get into using an actual map in as safe of was as is practical.
+ */
+function objectToMap(objectMap) {
+    const map = new Map();
+    // This function must only be used with objects specifically intended to encode map like information.
+    for (const key of Object.keys(objectMap)) {
+        const element = objectMap[key];
+        map.set(key, element);
+    }
+    return map;
+}
+exports.objectToMap = objectToMap;
+/**
+ * Convert an object used as a map into a new object used like a map.
+ *
+ * @remarks
+ * This function must only be used with objects specifically intended to encode map like information.
+ * The only time such objects should be used is for encoding maps as object literals to allow for developer ergonomics or JSON compatibility.
+ * Even those two use-cases need to be carefully considered as using objects as maps can have a lot of issues
+ * (including but not limited to unintended access to __proto__ and other non-owned keys).
+ * {@link objectToMap} helps these few cases get into using an actual map in as safe of a way as is practical.
+ */
+function transformObjectMap(objectMap, transformer) {
+    const output = Object.create(null);
+    // This function must only be used with objects specifically intended to encode map like information.
+    for (const key of Object.keys(objectMap)) {
+        const element = objectMap[key];
+        Object.defineProperty(output, key, {
+            enumerable: true,
+            configurable: true,
+            writable: true,
+            value: transformer(element, key),
+        });
+    }
+    return output;
+}
+exports.transformObjectMap = transformObjectMap;
+/**
+ * Make an inverted copy of a map.
+ *
+ * @returns a map which can look up the keys from the values of the original map.
+ */
+function invertMap(input) {
+    const result = new Map(mapIterable(input, ([key, value]) => [value, key]));
+    (0, core_utils_1.assert)(result.size === input.size, "all values in a map must be unique to invert it");
+    return result;
+}
+exports.invertMap = invertMap;
+/**
+ * Returns the value from `set` if it contains exactly one item, otherwise `undefined`.
+ * @internal
+ */
+function oneFromSet(set) {
+    if (set === undefined) {
+        return undefined;
+    }
+    if (set.size !== 1) {
+        return undefined;
+    }
+    for (const item of set) {
+        return item;
+    }
+}
+exports.oneFromSet = oneFromSet;
+/**
+ * Order {@link Named} objects by their name.
+ * @internal
+ */
+function compareNamed(a, b) {
+    if (a.name < b.name) {
+        return -1;
+    }
+    if (a.name > b.name) {
+        return 1;
+    }
+    return 0;
+}
+exports.compareNamed = compareNamed;
+/**
+ * Placeholder for `Symbol.dispose`.
+ *
+ * Replace this with `Symbol.dispose` when it is available.
+ * @beta
+ */
+exports.disposeSymbol = Symbol("Symbol.dispose placeholder");
+/**
+ * Capitalize a string.
+ */
+function capitalize(s) {
+    // To avoid splitting characters which are made of multiple UTF-16 code units,
+    // use iteration instead of indexing to separate the first character.
+    const iterated = s[Symbol.iterator]().next();
+    if (iterated.done === true) {
+        // Empty string case.
+        return "";
+    }
+    return (iterated.value.toUpperCase() + s.slice(iterated.value.length));
+}
+exports.capitalize = capitalize;
+/**
+ * Compares strings lexically to form a strict partial ordering.
+ */
+function compareStrings(a, b) {
+    return a > b ? 1 : a === b ? 0 : -1;
+}
+exports.compareStrings = compareStrings;
+//# sourceMappingURL=utils.js.map

package/dist/util/utils.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.js","sourceRoot":"","sources":["../../src/util/utils.ts"],"names":[],"mappings":"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","sourcesContent":["/*!\n * Copyright (c) Microsoft Corporation and contributors. All rights reserved.\n * Licensed under the MIT License.\n */\n\nimport { assert } from \"@fluidframework/core-utils\";\nimport { Type } from \"@sinclair/typebox\";\nimport structuredClone from \"@ungap/structured-clone\";\nimport {\n\tgenerateStableId as runtimeGenerateStableId,\n\tassertIsStableId,\n\tStableId,\n} from \"@fluidframework/id-compressor\";\n\n/**\n * Subset of Map interface.\n */\nexport interface MapGetSet<K, V> {\n\tget(key: K): V | undefined;\n\tset(key: K, value: V): void;\n}\n\n/**\n * Make all transitive properties in T readonly\n */\nexport type RecursiveReadonly<T> = {\n\treadonly [P in keyof T]: RecursiveReadonly<T[P]>;\n};\n\n/**\n * Remove `readonly` from all fields.\n */\nexport type Mutable<T> = { -readonly [P in keyof T]: T[P] };\n\n/**\n * Make all field required and omits fields whose ony valid value would be `undefined`.\n * This is analogous to `Required<T>` except it tolerates 'optional undefined'.\n */\nexport type Populated<T> = {\n\t[P in keyof T as Exclude<P, T[P] extends undefined ? P : never>]-?: T[P];\n};\n\n/**\n * Casts a readonly object to a mutable one.\n * Better than casting to `Mutable<Foo>` because it doesn't risk casting a non-`Foo` to a `Mutable<Foo>`.\n * @param readonly - The object with readonly fields.\n * @returns The same object but with a type that makes all fields mutable.\n */\nexport function asMutable<T>(readonly: T): Mutable<T> {\n\treturn readonly as Mutable<T>;\n}\n\nexport const clone = structuredClone;\n\n/**\n * @internal\n */\nexport function fail(message: string): never {\n\tthrow new Error(message);\n}\n\n/**\n * Checks whether or not the given object is a `readonly` array.\n *\n * Note that this does NOT indicate if a given array should be treated as readonly.\n * This instead indicates if an object is an Array, and is typed to tolerate the readonly case.\n */\nexport function isReadonlyArray<T>(x: readonly T[] | unknown): x is readonly T[] {\n\t// `Array.isArray()` does not properly narrow `readonly` array types by itself,\n\t// so we wrap it in this type guard. This may become unnecessary if/when\n\t// https://github.com/microsoft/TypeScript/issues/17002 is resolved.\n\treturn Array.isArray(x);\n}\n\n/**\n * Creates and populates a new array.\n * @param size - The size of the array to be created.\n * @param filler - Callback for populating the array with a value for a given index\n */\nexport function makeArray<T>(size: number, filler: (index: number) => T): T[] {\n\tconst array = [];\n\tfor (let i = 0; i < size; ++i) {\n\t\tarray.push(filler(i));\n\t}\n\treturn array;\n}\n\n/**\n * Compares two sets using callbacks.\n * Early returns on first false comparison.\n *\n * @param a - One Set.\n * @param b - The other Set.\n * @param aExtra - Called for items in `a` but not `b`.\n * @param bExtra - Called for items in `b` but not `a`.\n * @param same - Called for items in `a` and `b`.\n * @returns false iff any of the call backs returned false.\n */\nexport function compareSets<T>({\n\ta,\n\tb,\n\taExtra,\n\tbExtra,\n\tsame,\n}: {\n\ta: ReadonlySet<T> | ReadonlyMap<T, unknown>;\n\tb: ReadonlySet<T> | ReadonlyMap<T, unknown>;\n\taExtra?: (t: T) => boolean;\n\tbExtra?: (t: T) => boolean;\n\tsame?: (t: T) => boolean;\n}): boolean {\n\tfor (const item of a.keys()) {\n\t\tif (!b.has(item)) {\n\t\t\tif (aExtra && !aExtra(item)) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t} else {\n\t\t\tif (same && !same(item)) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t}\n\tfor (const item of b.keys()) {\n\t\tif (!a.has(item)) {\n\t\t\tif (bExtra && !bExtra(item)) {\n\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t}\n\treturn true;\n}\n\n/**\n * Retrieve a value from a map with the given key, or create a new entry if the key is not in the map.\n * @param map - The map to query/update\n * @param key - The key to lookup in the map\n * @param defaultValue - a function which returns a default value. This is called and used to set an initial value for the given key in the map if none exists\n * @returns either the existing value for the given key, or the newly-created value (the result of `defaultValue`)\n */\nexport function getOrCreate<K, V>(map: MapGetSet<K, V>, key: K, defaultValue: (key: K) => V): V {\n\tlet value = map.get(key);\n\tif (value === undefined) {\n\t\tvalue = defaultValue(key);\n\t\tmap.set(key, value);\n\t}\n\treturn value;\n}\n\n/**\n * Utility for dictionaries whose values are lists.\n * Gets the list associated with the provided key, if it exists.\n * Otherwise, creates an entry with an empty list, and returns that list.\n */\nexport function getOrAddEmptyToMap<K, V>(map: MapGetSet<K, V[]>, key: K): V[] {\n\tlet collection = map.get(key);\n\tif (collection === undefined) {\n\t\tcollection = [];\n\t\tmap.set(key, collection);\n\t}\n\treturn collection;\n}\n\n/**\n * Map one iterable to another by transforming each element one at a time\n * @param iterable - the iterable to transform\n * @param map - the transformation function to run on each element of the iterable\n * @returns a new iterable of elements which have been transformed by the `map` function\n */\nexport function* mapIterable<T, U>(iterable: Iterable<T>, map: (t: T) => U): Iterable<U> {\n\tfor (const t of iterable) {\n\t\tyield map(t);\n\t}\n}\n\n/**\n * Returns an iterable of tuples containing pairs of elements from the given iterables\n * @param iterableA - an iterable to zip together with `iterableB`\n * @param iterableB - an iterable to zip together with `iterableA`\n * @returns in iterable of tuples of elements zipped together from `iterableA` and `iterableB`.\n * If the input iterables are of different lengths, then the extra elements in the longer will be ignored.\n */\nexport function* zipIterables<T, U>(\n\titerableA: Iterable<T>,\n\titerableB: Iterable<U>,\n): Iterable<[T, U]> {\n\tconst iteratorA = iterableA[Symbol.iterator]();\n\tconst iteratorB = iterableB[Symbol.iterator]();\n\tfor (\n\t\tlet nextA = iteratorA.next(), nextB = iteratorB.next();\n\t\tnextA.done !== true && nextB.done !== true;\n\t\tnextA = iteratorA.next(), nextB = iteratorB.next()\n\t) {\n\t\tyield [nextA.value, nextB.value];\n\t}\n}\n\n/**\n * Use for Json compatible data.\n *\n * Note that this does not robustly forbid non json comparable data via type checking,\n * but instead mostly restricts access to it.\n * @internal\n */\nexport type JsonCompatible =\n\t| string\n\t| number\n\t| boolean\n\t// eslint-disable-next-line @rushstack/no-new-null\n\t| null\n\t| JsonCompatible[]\n\t| JsonCompatibleObject;\n\n/**\n * Use for Json object compatible data.\n *\n * Note that this does not robustly forbid non json comparable data via type checking,\n * but instead mostly restricts access to it.\n * @internal\n */\nexport type JsonCompatibleObject = { [P in string]?: JsonCompatible };\n\n/**\n * Use for readonly view of Json compatible data.\n *\n * Note that this does not robustly forbid non json comparable data via type checking,\n * but instead mostly restricts access to it.\n * @internal\n */\nexport type JsonCompatibleReadOnly =\n\t| string\n\t| number\n\t| boolean\n\t// eslint-disable-next-line @rushstack/no-new-null\n\t| null\n\t| readonly JsonCompatibleReadOnly[]\n\t| { readonly [P in string]?: JsonCompatibleReadOnly };\n\n/**\n * @remarks TODO: Audit usage of this type in schemas, evaluating whether it is necessary and performance\n * of alternatives.\n *\n * True \"arbitrary serializable data\" is probably fine, but some persisted types declarations might be better\n * expressed using composition of schemas for runtime validation, even if we don't think making the types\n * generic is worth the maintenance cost.\n */\nexport const JsonCompatibleReadOnlySchema = Type.Any();\n\n/**\n * Returns if a particular json compatible value is an object.\n * Does not include `null` or arrays.\n */\nexport function isJsonObject(\n\tvalue: JsonCompatibleReadOnly,\n): value is { readonly [P in string]?: JsonCompatibleReadOnly } {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\n/**\n * Verifies that the supplied indices are valid within the supplied array.\n * @param startIndex - The starting index in the range. Must be in [0, length).\n * @param endIndex - The ending index in the range. Must be within (start, length].\n * @param array - The array the indices refer to\n */\nexport function assertValidRangeIndices(\n\tstartIndex: number,\n\tendIndex: number,\n\tarray: { readonly length: number },\n) {\n\tassert(endIndex >= startIndex, 0x79c /* Range indices are malformed. */);\n\tassertValidIndex(startIndex, array, false);\n\tassertValidIndex(endIndex, array, true);\n}\n\nexport function assertValidIndex(\n\tindex: number,\n\tarray: { readonly length: number },\n\tallowOnePastEnd: boolean = false,\n) {\n\tassertNonNegativeSafeInteger(index);\n\tif (allowOnePastEnd) {\n\t\tassert(index <= array.length, 0x378 /* index must be less than or equal to length */);\n\t} else {\n\t\tassert(index < array.length, 0x379 /* index must be less than length */);\n\t}\n}\n\nexport function assertValidRange(\n\t{ start, end }: { start: number; end: number },\n\tarray: { readonly length: number },\n) {\n\tassertNonNegativeSafeInteger(start);\n\tassertNonNegativeSafeInteger(end);\n\tassert(end <= array.length, 0x79d /* Range end must be less than or equal to length */);\n\tassert(start <= end, 0x79e /* Range start must be less than or equal to range start */);\n}\n\nexport function assertNonNegativeSafeInteger(index: number) {\n\tassert(Number.isSafeInteger(index), 0x376 /* index must be an integer */);\n\tassert(index >= 0, 0x377 /* index must be non-negative */);\n}\n\n/**\n * Assume that `TInput` is a `TAssumeToBe`.\n *\n * @remarks\n * This is useful in generic code when it is impractical (or messy)\n * to to convince the compiler that a generic type `TInput` will extend `TAssumeToBe`.\n * In these cases `TInput` can be replaced with `Assume<TInput, TAssumeToBe>` to allow compilation of the generic code.\n * When the generic code is parameterized with a concrete type, if that type actually does extend `TAssumeToBe`,\n * it will behave like `TInput` was used directly.\n *\n * @internal\n */\nexport type Assume<TInput, TAssumeToBe> = [TInput] extends [TAssumeToBe] ? TInput : TAssumeToBe;\n\n/**\n * The counter used to generate deterministic stable ids for testing purposes.\n */\nlet deterministicStableIdCount: number | undefined;\n\n/**\n * Runs `f` with {@link generateStableId} altered to return sequential StableIds starting as a fixed seed.\n * Used to make test logic that uses {@link generateStableId} deterministic.\n *\n * @remarks Only use this function for testing purposes.\n *\n * @example\n *\n * ```typescript\n * function f() {\n *    const id = generateStableId();\n *    ...\n * }\n * const result = useDeterministicStableId(f());\n * ```\n */\nexport function useDeterministicStableId<T>(f: () => T): T {\n\tassert(\n\t\tdeterministicStableIdCount === undefined,\n\t\t0x6ce /* useDeterministicStableId cannot be nested */,\n\t);\n\tdeterministicStableIdCount = 1;\n\ttry {\n\t\treturn f();\n\t\t// Since this is intended to be used by tests, and test runners often recover from exceptions to run more tests,\n\t\t// clean this up with a finally block to reduce risk of breaking unrelated tests after a failure.\n\t} finally {\n\t\tdeterministicStableIdCount = undefined;\n\t}\n}\n\nexport async function useAsyncDeterministicStableId<T>(f: () => Promise<T>): Promise<T> {\n\tassert(\n\t\tdeterministicStableIdCount === undefined,\n\t\t0x79f /* useAsyncDeterministicStableId cannot be nested */,\n\t);\n\tdeterministicStableIdCount = 1;\n\ttry {\n\t\treturn await f();\n\t\t// Since this is intended to be used by tests, and test runners often recover from exceptions to run more tests,\n\t\t// clean this up with a finally block to reduce risk of breaking unrelated tests after a failure.\n\t} finally {\n\t\tdeterministicStableIdCount = undefined;\n\t}\n}\n\n/**\n * Generates a random StableId.\n *\n * For test usage desiring deterministic results, see {@link useDeterministicStableId}.\n */\nexport function generateStableId(): StableId {\n\tif (deterministicStableIdCount !== undefined) {\n\t\tassert(\n\t\t\tdeterministicStableIdCount < 281_474_976_710_656,\n\t\t\t0x6cf /* The maximum valid value for deterministicStableIdCount is 16^12 */,\n\t\t);\n\t\t// Tried to generate a unique id prefixing it with the word 'beef'\n\t\treturn assertIsStableId(\n\t\t\t`beefbeef-beef-4000-8000-${(deterministicStableIdCount++)\n\t\t\t\t.toString(16)\n\t\t\t\t.padStart(12, \"0\")}`,\n\t\t);\n\t}\n\treturn runtimeGenerateStableId();\n}\n\n/**\n * Convert an object into a Map.\n *\n * This function must only be used with objects specifically intended to encode map like information.\n * The only time such objects should be used is for encoding maps as object literals to allow for developer ergonomics or JSON compatibility.\n * Even those two use-cases need to be carefully considered as using objects as maps can have a lot of issues\n * (including but not limited to unintended access to __proto__ and other non-owned keys).\n * This function helps these few cases get into using an actual map in as safe of was as is practical.\n */\nexport function objectToMap<MapKey extends string | number | symbol, MapValue>(\n\tobjectMap: Record<MapKey, MapValue>,\n): Map<MapKey, MapValue> {\n\tconst map = new Map<MapKey, MapValue>();\n\t// This function must only be used with objects specifically intended to encode map like information.\n\tfor (const key of Object.keys(objectMap)) {\n\t\tconst element = objectMap[key as MapKey];\n\t\tmap.set(key as MapKey, element);\n\t}\n\treturn map;\n}\n\n/**\n * Convert an object used as a map into a new object used like a map.\n *\n * @remarks\n * This function must only be used with objects specifically intended to encode map like information.\n * The only time such objects should be used is for encoding maps as object literals to allow for developer ergonomics or JSON compatibility.\n * Even those two use-cases need to be carefully considered as using objects as maps can have a lot of issues\n * (including but not limited to unintended access to __proto__ and other non-owned keys).\n * {@link objectToMap} helps these few cases get into using an actual map in as safe of a way as is practical.\n */\nexport function transformObjectMap<MapKey extends string | number | symbol, MapValue, NewMapValue>(\n\tobjectMap: Record<MapKey, MapValue>,\n\ttransformer: (value: MapValue, key: MapKey) => NewMapValue,\n): Record<MapKey, MapValue> {\n\tconst output: Record<MapKey, MapValue> = Object.create(null);\n\t// This function must only be used with objects specifically intended to encode map like information.\n\tfor (const key of Object.keys(objectMap)) {\n\t\tconst element = objectMap[key as MapKey];\n\t\tObject.defineProperty(output, key, {\n\t\t\tenumerable: true,\n\t\t\tconfigurable: true,\n\t\t\twritable: true,\n\t\t\tvalue: transformer(element, key as MapKey),\n\t\t});\n\t}\n\treturn output;\n}\n\n/**\n * Make an inverted copy of a map.\n *\n * @returns a map which can look up the keys from the values of the original map.\n */\nexport function invertMap<Key, Value>(input: Map<Key, Value>): Map<Value, Key> {\n\tconst result = new Map<Value, Key>(mapIterable(input, ([key, value]) => [value, key]));\n\tassert(result.size === input.size, \"all values in a map must be unique to invert it\");\n\treturn result;\n}\n\n/**\n * Returns the value from `set` if it contains exactly one item, otherwise `undefined`.\n * @internal\n */\nexport function oneFromSet<T>(set: ReadonlySet<T> | undefined): T | undefined {\n\tif (set === undefined) {\n\t\treturn undefined;\n\t}\n\tif (set.size !== 1) {\n\t\treturn undefined;\n\t}\n\tfor (const item of set) {\n\t\treturn item;\n\t}\n}\n\n/**\n * Type with a name describing what it is.\n * Typically used with values (like schema) that can be stored in a map, but in some representations have their name/key as a field.\n * @internal\n */\nexport interface Named<TName> {\n\treadonly name: TName;\n}\n\n/**\n * Order {@link Named} objects by their name.\n * @internal\n */\nexport function compareNamed(a: Named<string>, b: Named<string>): -1 | 0 | 1 {\n\tif (a.name < b.name) {\n\t\treturn -1;\n\t}\n\tif (a.name > b.name) {\n\t\treturn 1;\n\t}\n\treturn 0;\n}\n\n/**\n * Placeholder for `Symbol.dispose`.\n *\n * Replace this with `Symbol.dispose` when it is available.\n * @beta\n */\nexport const disposeSymbol: unique symbol = Symbol(\"Symbol.dispose placeholder\");\n\n/**\n * An object with an explicit lifetime that can be ended.\n * @privateRemarks\n * TODO: align this with core-utils/IDisposable and {@link https://www.typescriptlang.org/docs/handbook/release-notes/typescript-5-2.html#using-declarations-and-explicit-resource-management| TypeScript's Disposable}.\n * @beta\n */\nexport interface IDisposable {\n\t/**\n\t * Call to end the lifetime of this object.\n\t *\n\t * It is invalid to use this object after this,\n\t * except for operations which explicitly document they are valid after disposal.\n\t *\n\t * @remarks\n\t * May cleanup resources retained by this object.\n\t * Often includes un-registering from events and thus preventing other objects from retaining a reference to this indefinably.\n\t *\n\t * Usually the only operations allowed after disposal are querying if an object is already disposed,\n\t * but this can vary between implementations.\n\t */\n\t[disposeSymbol](): void;\n}\n\n/**\n * Capitalize a string.\n */\nexport function capitalize<S extends string>(s: S): Capitalize<S> {\n\t// To avoid splitting characters which are made of multiple UTF-16 code units,\n\t// use iteration instead of indexing to separate the first character.\n\tconst iterated = s[Symbol.iterator]().next();\n\tif (iterated.done === true) {\n\t\t// Empty string case.\n\t\treturn \"\" as Capitalize<S>;\n\t}\n\n\treturn (iterated.value.toUpperCase() + s.slice(iterated.value.length)) as Capitalize<S>;\n}\n\n/**\n * Compares strings lexically to form a strict partial ordering.\n */\nexport function compareStrings<T extends string>(a: T, b: T): number {\n\treturn a > b ? 1 : a === b ? 0 : -1;\n}\n"]}

package/docs/.attachments/UndoDangerZone.drawio

@@ -0,0 +1 @@
+<mxfile host="Electron" modified="2023-06-08T21:22:07.766Z" agent="5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) draw.io/13.9.9 Chrome/85.0.4183.121 Electron/10.1.5 Safari/537.36" etag="iNhSQ7ApMGTfDy_I7_HD" version="13.9.9" type="device"><diagram id="-6H5wynXqOOyBtFPYk5a" name="Page-1">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</diagram></mxfile>