@tldraw/utils 4.1.0-next.b6dfe9bccde9 → 4.1.0-next.b73a0d46b63f

package/src/lib/object.ts

@@ -1,11 +1,42 @@
 import isEqualWith from 'lodash.isequalwith'
 
-/** @internal */
+/**
+ * Safely checks if an object has a specific property as its own property (not inherited).
+ * Uses Object.prototype.hasOwnProperty.call to avoid issues with objects that have null prototype
+ * or have overridden the hasOwnProperty method.
+ *
+ * @param obj - The object to check
+ * @param key - The property key to check for
+ * @returns True if the object has the property as its own property, false otherwise
+ * @example
+ * ```ts
+ * const obj = { name: 'Alice', age: 30 }
+ * hasOwnProperty(obj, 'name') // true
+ * hasOwnProperty(obj, 'toString') // false (inherited)
+ * hasOwnProperty(obj, 'unknown') // false
+ * ```
+ * @internal
+ */
 export function hasOwnProperty(obj: object, key: string): boolean {
 	return Object.prototype.hasOwnProperty.call(obj, key)
 }
 
-/** @internal */
+/**
+ * Safely gets an object's own property value (not inherited). Returns undefined if the property
+ * doesn't exist as an own property. Provides type-safe access with proper TypeScript inference.
+ *
+ * @param obj - The object to get the property from
+ * @param key - The property key to retrieve
+ * @returns The property value if it exists as an own property, undefined otherwise
+ * @example
+ * ```ts
+ * const user = { name: 'Alice', age: 30 }
+ * const name = getOwnProperty(user, 'name') // 'Alice'
+ * const missing = getOwnProperty(user, 'unknown') // undefined
+ * const inherited = getOwnProperty(user, 'toString') // undefined (inherited)
+ * ```
+ * @internal
+ */
 export function getOwnProperty<K extends string, V>(
 	obj: Partial<Record<K, V>>,
 	key: K
@@ -25,7 +56,16 @@ export function getOwnProperty(obj: object, key: string): unknown {
 
 /**
  * An alias for `Object.keys` that treats the object as a map and so preserves the type of the keys.
+ * Unlike standard Object.keys which returns string[], this maintains the specific string literal types.
  *
+ * @param object - The object to get keys from
+ * @returns Array of keys with preserved string literal types
+ * @example
+ * ```ts
+ * const config = { theme: 'dark', lang: 'en' } as const
+ * const keys = objectMapKeys(config)
+ * // keys is Array<'theme' | 'lang'> instead of string[]
+ * ```
  * @internal
  */
 export function objectMapKeys<Key extends string>(object: {
@@ -36,8 +76,16 @@ export function objectMapKeys<Key extends string>(object: {
 
 /**
  * An alias for `Object.values` that treats the object as a map and so preserves the type of the
- * keys.
+ * values. Unlike standard Object.values which returns unknown[], this maintains the specific value types.
  *
+ * @param object - The object to get values from
+ * @returns Array of values with preserved types
+ * @example
+ * ```ts
+ * const scores = { alice: 85, bob: 92, charlie: 78 }
+ * const values = objectMapValues(scores)
+ * // values is Array<number> instead of unknown[]
+ * ```
  * @internal
  */
 export function objectMapValues<Key extends string, Value>(object: {
@@ -48,8 +96,16 @@ export function objectMapValues<Key extends string, Value>(object: {
 
 /**
  * An alias for `Object.entries` that treats the object as a map and so preserves the type of the
- * keys.
+ * keys and values. Unlike standard Object.entries which returns `Array<[string, unknown]>`, this maintains specific types.
  *
+ * @param object - The object to get entries from
+ * @returns Array of key-value pairs with preserved types
+ * @example
+ * ```ts
+ * const user = { name: 'Alice', age: 30 }
+ * const entries = objectMapEntries(user)
+ * // entries is Array<['name' | 'age', string | number]>
+ * ```
  * @internal
  */
 export function objectMapEntries<Key extends string, Value>(object: {
@@ -61,7 +117,18 @@ export function objectMapEntries<Key extends string, Value>(object: {
 /**
  * Returns the entries of an object as an iterable iterator.
  * Useful when working with large collections, to avoid allocating an array.
+ * Only yields own properties (not inherited ones).
  *
+ * @param object - The object to iterate over
+ * @returns Iterator yielding key-value pairs with preserved types
+ * @example
+ * ```ts
+ * const largeMap = { a: 1, b: 2, c: 3 } // Imagine thousands of entries
+ * for (const [key, value] of objectMapEntriesIterable(largeMap)) {
+ *   // Process entries one at a time without creating a large array
+ *   console.log(key, value)
+ * }
+ * ```
  * @internal
  */
 export function* objectMapEntriesIterable<Key extends string, Value>(object: {
@@ -75,8 +142,16 @@ export function* objectMapEntriesIterable<Key extends string, Value>(object: {
 
 /**
  * An alias for `Object.fromEntries` that treats the object as a map and so preserves the type of the
- * keys.
+ * keys and values. Creates an object from key-value pairs with proper TypeScript typing.
  *
+ * @param entries - Array of key-value pairs to convert to an object
+ * @returns Object with preserved key and value types
+ * @example
+ * ```ts
+ * const pairs: Array<['name' | 'age', string | number]> = [['name', 'Alice'], ['age', 30]]
+ * const obj = objectMapFromEntries(pairs)
+ * // obj is { name: string | number, age: string | number }
+ * ```
  * @internal
  */
 export function objectMapFromEntries<Key extends string, Value>(
@@ -86,8 +161,18 @@ export function objectMapFromEntries<Key extends string, Value>(
 }
 
 /**
- * Filters an object using a predicate function.
- * @returns a new object with only the entries that pass the predicate
+ * Filters an object using a predicate function, returning a new object with only the entries
+ * that pass the predicate. Optimized to return the original object if no changes are needed.
+ *
+ * @param object - The object to filter
+ * @param predicate - Function that tests each key-value pair
+ * @returns A new object with only the entries that pass the predicate, or the original object if unchanged
+ * @example
+ * ```ts
+ * const scores = { alice: 85, bob: 92, charlie: 78 }
+ * const passing = filterEntries(scores, (name, score) => score >= 80)
+ * // { alice: 85, bob: 92 }
+ * ```
  * @internal
  */
 export function filterEntries<Key extends string, Value>(
@@ -107,8 +192,18 @@ export function filterEntries<Key extends string, Value>(
 }
 
 /**
- * Maps the values of one object map to another.
- * @returns a new object with the entries mapped
+ * Maps the values of an object to new values using a mapper function, preserving keys.
+ * The mapper function receives both the key and value for each entry.
+ *
+ * @param object - The object whose values to transform
+ * @param mapper - Function that transforms each value (receives key and value)
+ * @returns A new object with the same keys but transformed values
+ * @example
+ * ```ts
+ * const prices = { apple: 1.50, banana: 0.75, orange: 2.00 }
+ * const withTax = mapObjectMapValues(prices, (fruit, price) => price * 1.08)
+ * // { apple: 1.62, banana: 0.81, orange: 2.16 }
+ * ```
  * @internal
  */
 export function mapObjectMapValues<Key extends string, ValueBefore, ValueAfter>(
@@ -123,7 +218,24 @@ export function mapObjectMapValues<Key extends string, ValueBefore, ValueAfter>(
 	return result
 }
 
-/** @internal */
+/**
+ * Performs a shallow equality check between two objects. Compares all enumerable own properties
+ * using Object.is for value comparison. Returns true if both objects have the same keys and values.
+ *
+ * @param obj1 - First object to compare
+ * @param obj2 - Second object to compare
+ * @returns True if objects are shallow equal, false otherwise
+ * @example
+ * ```ts
+ * const a = { x: 1, y: 2 }
+ * const b = { x: 1, y: 2 }
+ * const c = { x: 1, y: 3 }
+ * areObjectsShallowEqual(a, b) // true
+ * areObjectsShallowEqual(a, c) // false
+ * areObjectsShallowEqual(a, a) // true (same reference)
+ * ```
+ * @internal
+ */
 export function areObjectsShallowEqual<T extends object>(obj1: T, obj2: T): boolean {
 	if (obj1 === obj2) return true
 	const keys1 = new Set(Object.keys(obj1))
@@ -136,7 +248,25 @@ export function areObjectsShallowEqual<T extends object>(obj1: T, obj2: T): bool
 	return true
 }
 
-/** @internal */
+/**
+ * Groups an array of values into a record by a key extracted from each value.
+ * The key selector function is called for each element to determine the grouping key.
+ *
+ * @param array - The array to group
+ * @param keySelector - Function that extracts the grouping key from each value
+ * @returns A record where keys are the extracted keys and values are arrays of grouped items
+ * @example
+ * ```ts
+ * const people = [
+ *   { name: 'Alice', age: 25 },
+ *   { name: 'Bob', age: 30 },
+ *   { name: 'Charlie', age: 25 }
+ * ]
+ * const byAge = groupBy(people, person => `age-${person.age}`)
+ * // { 'age-25': [Alice, Charlie], 'age-30': [Bob] }
+ * ```
+ * @internal
+ */
 export function groupBy<K extends string, V>(
 	array: ReadonlyArray<V>,
 	keySelector: (value: V) => K
@@ -150,7 +280,21 @@ export function groupBy<K extends string, V>(
 	return result
 }
 
-/** @internal */
+/**
+ * Creates a new object with specified keys omitted from the original object.
+ * Uses shallow copying and then deletes the unwanted keys.
+ *
+ * @param obj - The source object
+ * @param keys - Array of key names to omit from the result
+ * @returns A new object without the specified keys
+ * @example
+ * ```ts
+ * const user = { id: '123', name: 'Alice', password: 'secret', email: 'alice@example.com' }
+ * const publicUser = omit(user, ['password'])
+ * // { id: '123', name: 'Alice', email: 'alice@example.com' }
+ * ```
+ * @internal
+ */
 export function omit(
 	obj: Record<string, unknown>,
 	keys: ReadonlyArray<string>
@@ -162,7 +306,23 @@ export function omit(
 	return result
 }
 
-/** @internal */
+/**
+ * Compares two objects and returns an array of keys where the values differ.
+ * Uses Object.is for comparison, which handles NaN and -0/+0 correctly.
+ * Only checks keys present in the first object.
+ *
+ * @param obj1 - The first object (keys to check come from this object)
+ * @param obj2 - The second object to compare against
+ * @returns Array of keys where values differ between the objects
+ * @example
+ * ```ts
+ * const before = { name: 'Alice', age: 25, city: 'NYC' }
+ * const after = { name: 'Alice', age: 26, city: 'NYC' }
+ * const changed = getChangedKeys(before, after)
+ * // ['age']
+ * ```
+ * @internal
+ */
 export function getChangedKeys<T extends object>(obj1: T, obj2: T): (keyof T)[] {
 	const result: (keyof T)[] = []
 	for (const key in obj1) {
@@ -173,7 +333,27 @@ export function getChangedKeys<T extends object>(obj1: T, obj2: T): (keyof T)[]
 	return result
 }
 
-/** @internal */
+/**
+ * Deep equality comparison that allows for floating-point precision errors.
+ * Numbers are considered equal if they differ by less than the threshold.
+ * Uses lodash.isequalwith internally for the deep comparison logic.
+ *
+ * @param obj1 - First object to compare
+ * @param obj2 - Second object to compare
+ * @param threshold - Maximum difference allowed between numbers (default: 0.000001)
+ * @returns True if objects are deeply equal with floating-point tolerance
+ * @example
+ * ```ts
+ * const a = { x: 0.1 + 0.2 } // 0.30000000000000004
+ * const b = { x: 0.3 }
+ * isEqualAllowingForFloatingPointErrors(a, b) // true
+ *
+ * const c = { coords: [1.0000001, 2.0000001] }
+ * const d = { coords: [1.0000002, 2.0000002] }
+ * isEqualAllowingForFloatingPointErrors(c, d) // true
+ * ```
+ * @internal
+ */
 export function isEqualAllowingForFloatingPointErrors(
 	obj1: object,
 	obj2: object,

package/src/lib/perf.ts

@@ -1,12 +1,41 @@
+/**
+ * Color scheme for performance indicators.
+ * Provides consistent colors for performance measurement displays.
+ *
+ * @public
+ */
 export const PERFORMANCE_COLORS = {
 	Good: '#40C057',
 	Mid: '#FFC078',
 	Poor: '#E03131',
 }
 
+/**
+ * Default color for performance measurement log prefixes.
+ * Uses the 'Good' performance color for console output styling.
+ *
+ * @public
+ */
 export const PERFORMANCE_PREFIX_COLOR = PERFORMANCE_COLORS.Good
 
-/** @internal */
+/**
+ * Measures and logs the execution time of a callback function.
+ * Executes the provided callback and logs the duration to the console with styled output.
+ *
+ * @param name - Descriptive name for the operation being measured
+ * @param cb - Callback function to execute and measure
+ * @returns The return value of the callback function
+ *
+ * @example
+ * ```ts
+ * const result = measureCbDuration('data processing', () => {
+ *   return processLargeDataSet(data)
+ * })
+ * // Console output: "Perf data processing took 42.5ms"
+ * ```
+ *
+ * @internal
+ */
 export function measureCbDuration(name: string, cb: () => any) {
 	const start = performance.now()
 	const result = cb()
@@ -19,7 +48,28 @@ export function measureCbDuration(name: string, cb: () => any) {
 	return result
 }
 
-/** @internal */
+/**
+ * Decorator that measures and logs the execution time of class methods.
+ * Wraps the decorated method to automatically log its execution duration.
+ *
+ * @param _target - The class prototype (unused)
+ * @param propertyKey - Name of the method being decorated
+ * @param descriptor - Property descriptor of the method
+ * @returns Modified property descriptor with timing measurement
+ *
+ * @example
+ * ```ts
+ * class DataProcessor {
+ *   @measureDuration
+ *   processData(data: unknown[]) {
+ *     return data.map(item => transform(item))
+ *   }
+ * }
+ * // When processData is called, logs: "Perf processData took: 15.2ms"
+ * ```
+ *
+ * @internal
+ */
 export function measureDuration(_target: any, propertyKey: string, descriptor: PropertyDescriptor) {
 	const originalMethod = descriptor.value
 	descriptor.value = function (...args: any[]) {
@@ -38,7 +88,29 @@ export function measureDuration(_target: any, propertyKey: string, descriptor: P
 
 const averages = new Map<any, { total: number; count: number }>()
 
-/** @internal */
+/**
+ * Decorator that measures method execution time and tracks running averages.
+ * Wraps the decorated method to log both current execution time and running average.
+ * Maintains a running total and count for each decorated method to calculate averages.
+ *
+ * @param _target - The class prototype (unused)
+ * @param propertyKey - Name of the method being decorated
+ * @param descriptor - Property descriptor of the method
+ * @returns Modified property descriptor with timing measurement and averaging
+ *
+ * @example
+ * ```ts
+ * class RenderEngine {
+ *   @measureAverageDuration
+ *   renderFrame() {
+ *     // Rendering logic here
+ *   }
+ * }
+ * // After multiple calls, logs: "Perf renderFrame took 16.67ms | average 15.83ms"
+ * ```
+ *
+ * @internal
+ */
 export function measureAverageDuration(
 	_target: any,
 	propertyKey: string,

package/src/lib/reordering.test.ts

@@ -0,0 +1,168 @@
+import { describe, expect, it } from 'vitest'
+import {
+	type IndexKey,
+	getIndexAbove,
+	getIndexBelow,
+	getIndexBetween,
+	getIndices,
+	getIndicesAbove,
+	getIndicesBelow,
+	getIndicesBetween,
+	sortByIndex,
+	validateIndexKey,
+} from './reordering'
+
+describe('reordering', () => {
+	describe('validateIndexKey', () => {
+		it('should accept valid index keys', () => {
+			expect(() => validateIndexKey('a0')).not.toThrow()
+			expect(() => validateIndexKey('a1')).not.toThrow()
+			expect(() => validateIndexKey('a0V')).not.toThrow()
+		})
+
+		it('should throw for invalid index keys', () => {
+			expect(() => validateIndexKey('')).toThrow('invalid index: ')
+			expect(() => validateIndexKey('invalid')).toThrow('invalid index: invalid')
+			expect(() => validateIndexKey('123')).toThrow('invalid index: 123')
+		})
+	})
+
+	describe('getIndicesBetween', () => {
+		it('should generate indices between two indices', () => {
+			const indices = getIndicesBetween('a0' as IndexKey, 'a2' as IndexKey, 2)
+			expect(indices).toHaveLength(2)
+			expect(indices.every((index) => index > 'a0' && index < 'a2')).toBe(true)
+		})
+
+		it('should handle null/undefined parameters', () => {
+			const indices1 = getIndicesBetween(null, 'a2' as IndexKey, 2)
+			expect(indices1).toHaveLength(2)
+			expect(indices1.every((index) => index < 'a2')).toBe(true)
+
+			const indices2 = getIndicesBetween('a0' as IndexKey, null, 2)
+			expect(indices2).toHaveLength(2)
+			expect(indices2.every((index) => index > 'a0')).toBe(true)
+		})
+	})
+
+	describe('getIndicesAbove', () => {
+		it('should generate indices above a given index', () => {
+			const indices = getIndicesAbove('a0' as IndexKey, 3)
+			expect(indices).toHaveLength(3)
+			expect(indices.every((index) => index > 'a0')).toBe(true)
+		})
+
+		it('should handle null/undefined parameters', () => {
+			const indices = getIndicesAbove(null, 3)
+			expect(indices).toHaveLength(3)
+		})
+	})
+
+	describe('getIndicesBelow', () => {
+		it('should generate indices below a given index', () => {
+			const indices = getIndicesBelow('a5' as IndexKey, 3)
+			expect(indices).toHaveLength(3)
+			expect(indices.every((index) => index < 'a5')).toBe(true)
+		})
+
+		it('should handle null/undefined parameters', () => {
+			const indices = getIndicesBelow(null, 3)
+			expect(indices).toHaveLength(3)
+		})
+	})
+
+	describe('getIndexBetween', () => {
+		it('should generate single index between two indices', () => {
+			const index = getIndexBetween('a0' as IndexKey, 'a2' as IndexKey)
+			expect(index > 'a0' && index < 'a2').toBe(true)
+		})
+
+		it('should handle null/undefined parameters', () => {
+			const index1 = getIndexBetween(null, 'a2' as IndexKey)
+			expect(index1 < 'a2').toBe(true)
+
+			const index2 = getIndexBetween('a0' as IndexKey, null)
+			expect(index2 > 'a0').toBe(true)
+		})
+	})
+
+	describe('getIndexAbove', () => {
+		it('should generate index above given index', () => {
+			const index = getIndexAbove('a0' as IndexKey)
+			expect(index > 'a0').toBe(true)
+		})
+
+		it('should handle null/undefined/no parameters', () => {
+			const index = getIndexAbove()
+			expect(typeof index).toBe('string')
+		})
+	})
+
+	describe('getIndexBelow', () => {
+		it('should generate index below given index', () => {
+			const index = getIndexBelow('a5' as IndexKey)
+			expect(index < 'a5').toBe(true)
+		})
+
+		it('should handle null/undefined/no parameters', () => {
+			const index = getIndexBelow()
+			expect(typeof index).toBe('string')
+		})
+	})
+
+	describe('getIndices', () => {
+		it('should generate indices starting from given index', () => {
+			const indices = getIndices(3, 'a1' as IndexKey)
+			expect(indices).toHaveLength(4) // start + n additional
+			expect(indices[0]).toBe('a1')
+			expect(indices.every((index) => index >= 'a1')).toBe(true)
+		})
+
+		it('should use default start index when not provided', () => {
+			const indices = getIndices(3)
+			expect(indices).toHaveLength(4)
+			expect(indices[0]).toBe('a1')
+		})
+	})
+
+	describe('sortByIndex', () => {
+		it('should sort objects by index property in ascending order', () => {
+			const objects = [
+				{ id: 'c', index: 'a3' as IndexKey },
+				{ id: 'a', index: 'a1' as IndexKey },
+				{ id: 'b', index: 'a2' as IndexKey },
+			]
+
+			const sorted = objects.sort(sortByIndex)
+			expect(sorted.map((obj) => obj.id)).toEqual(['a', 'b', 'c'])
+		})
+
+		it('should handle fractional indices correctly', () => {
+			const objects = [
+				{ id: 'c', index: 'a1V' as IndexKey }, // Between a1 and a2
+				{ id: 'a', index: 'a1' as IndexKey },
+				{ id: 'b', index: 'a2' as IndexKey },
+			]
+
+			const sorted = objects.sort(sortByIndex)
+			expect(sorted.map((obj) => obj.id)).toEqual(['a', 'c', 'b'])
+		})
+	})
+
+	describe('integration tests', () => {
+		it('should maintain order when inserting indices between existing ones', () => {
+			const start = getIndexAbove()
+			const end = getIndexAbove(start)
+			const between = getIndexBetween(start, end)
+
+			const objects = [
+				{ id: 'first', index: start },
+				{ id: 'last', index: end },
+				{ id: 'middle', index: between },
+			]
+
+			const sorted = objects.sort(sortByIndex)
+			expect(sorted.map((obj) => obj.id)).toEqual(['first', 'middle', 'last'])
+		})
+	})
+})

package/src/lib/reordering.ts

@@ -22,7 +22,12 @@ export type IndexKey = string & { __brand: 'indexKey' }
  */
 export const ZERO_INDEX_KEY = 'a0' as IndexKey
 
-/** @internal */
+/**
+ * Validates that a string is a valid IndexKey.
+ * @param index - The string to validate.
+ * @throws Error if the index is invalid.
+ * @internal
+ */
 export function validateIndexKey(index: string): asserts index is IndexKey {
 	try {
 		generateKeyBetween(index, null)
@@ -36,6 +41,12 @@ export function validateIndexKey(index: string): asserts index is IndexKey {
  * @param below - The index below.
  * @param above - The index above.
  * @param n - The number of indices to get.
+ * @returns An array of n IndexKey values between below and above.
+ * @example
+ * ```ts
+ * const indices = getIndicesBetween('a0' as IndexKey, 'a2' as IndexKey, 2)
+ * console.log(indices) // ['a0V', 'a1']
+ * ```
  * @public
  */
 export function getIndicesBetween(
@@ -50,6 +61,12 @@ export function getIndicesBetween(
  * Get a number of indices above an index.
  * @param below - The index below.
  * @param n - The number of indices to get.
+ * @returns An array of n IndexKey values above the given index.
+ * @example
+ * ```ts
+ * const indices = getIndicesAbove('a0' as IndexKey, 3)
+ * console.log(indices) // ['a1', 'a2', 'a3']
+ * ```
  * @public
  */
 export function getIndicesAbove(below: IndexKey | null | undefined, n: number) {
@@ -60,6 +77,12 @@ export function getIndicesAbove(below: IndexKey | null | undefined, n: number) {
  * Get a number of indices below an index.
  * @param above - The index above.
  * @param n - The number of indices to get.
+ * @returns An array of n IndexKey values below the given index.
+ * @example
+ * ```ts
+ * const indices = getIndicesBelow('a2' as IndexKey, 2)
+ * console.log(indices) // ['a1', 'a0V']
+ * ```
  * @public
  */
 export function getIndicesBelow(above: IndexKey | null | undefined, n: number) {
@@ -70,6 +93,12 @@ export function getIndicesBelow(above: IndexKey | null | undefined, n: number) {
  * Get the index between two indices.
  * @param below - The index below.
  * @param above - The index above.
+ * @returns A single IndexKey value between below and above.
+ * @example
+ * ```ts
+ * const index = getIndexBetween('a0' as IndexKey, 'a2' as IndexKey)
+ * console.log(index) // 'a1'
+ * ```
  * @public
  */
 export function getIndexBetween(
@@ -82,6 +111,12 @@ export function getIndexBetween(
 /**
  * Get the index above a given index.
  * @param below - The index below.
+ * @returns An IndexKey value above the given index.
+ * @example
+ * ```ts
+ * const index = getIndexAbove('a0' as IndexKey)
+ * console.log(index) // 'a1'
+ * ```
  * @public
  */
 export function getIndexAbove(below: IndexKey | null | undefined = null) {
@@ -91,7 +126,13 @@ export function getIndexAbove(below: IndexKey | null | undefined = null) {
 /**
  * Get the index below a given index.
  * @param above - The index above.
- *  @public
+ * @returns An IndexKey value below the given index.
+ * @example
+ * ```ts
+ * const index = getIndexBelow('a2' as IndexKey)
+ * console.log(index) // 'a1'
+ * ```
+ * @public
  */
 export function getIndexBelow(above: IndexKey | null | undefined = null) {
 	return generateKeysFn(null, above, 1)[0] as IndexKey
@@ -100,7 +141,13 @@ export function getIndexBelow(above: IndexKey | null | undefined = null) {
 /**
  * Get n number of indices, starting at an index.
  * @param n - The number of indices to get.
- * @param start -  The index to start at.
+ * @param start - The index to start at.
+ * @returns An array containing the start index plus n additional IndexKey values.
+ * @example
+ * ```ts
+ * const indices = getIndices(3, 'a1' as IndexKey)
+ * console.log(indices) // ['a1', 'a2', 'a3', 'a4']
+ * ```
  * @public
  */
 export function getIndices(n: number, start = 'a1' as IndexKey) {
@@ -111,7 +158,18 @@ export function getIndices(n: number, start = 'a1' as IndexKey) {
  * Sort by index.
  * @param a - An object with an index property.
  * @param b - An object with an index property.
- * @public */
+ * @returns A number indicating sort order (-1, 0, or 1).
+ * @example
+ * ```ts
+ * const shapes = [
+ *   { id: 'b', index: 'a2' as IndexKey },
+ *   { id: 'a', index: 'a1' as IndexKey }
+ * ]
+ * const sorted = shapes.sort(sortByIndex)
+ * console.log(sorted) // [{ id: 'a', index: 'a1' }, { id: 'b', index: 'a2' }]
+ * ```
+ * @public
+ */
 export function sortByIndex<T extends { index: IndexKey }>(a: T, b: T) {
 	if (a.index < b.index) {
 		return -1