/** * "What data are available": walks a live object into a compact type * SKELETON (keys and type names, no values) so users can see the shape of a * source while composing queries, independent of any query. * * - primitives -> their type name ('string', 'number', ...) * - functions -> 'function' * - arrays -> [skeleton of first item, '+N more'] * - Map/Set (incl. -like)-> 'Map(size) { => }' expansions * - class instances -> own props + $class tag * - circular -> '[circular]' * - depth/prop caps -> '...' */ import type { NormalizeOptions } from './normalize' import { isExcludedKey } from './normalize' export type SkeletonOptions = Pick< NormalizeOptions, 'maxDepth' | 'maxProps' | 'excludeFunctions' | 'excludeUnderscoreProps' | 'excludeDollarProps' > interface SkeletonWalker { seen: WeakSet nodes: number opts: Required } export function skeletonOf(value: unknown, options: SkeletonOptions = {}): { skeleton: unknown, nodes: number, ms: number } { const started = performance.now() const walker: SkeletonWalker = { seen: new WeakSet(), nodes: 0, opts: { maxDepth: options.maxDepth ?? 5, maxProps: options.maxProps ?? 80, excludeFunctions: options.excludeFunctions ?? false, excludeUnderscoreProps: options.excludeUnderscoreProps ?? false, excludeDollarProps: options.excludeDollarProps ?? false, }, } const skeleton = walk(value, walker, 0) return { skeleton, nodes: walker.nodes, ms: Math.round((performance.now() - started) * 100) / 100 } } function isMapLike(v: object): v is Map { return typeof (v as Map).entries === 'function' && typeof (v as Map).get === 'function' && typeof (v as Map).size === 'number' } function isSetLike(v: object): v is Set { return typeof (v as Set).has === 'function' && typeof (v as Set)[Symbol.iterator] === 'function' && typeof (v as Map).get !== 'function' && typeof (v as Set).size === 'number' } function walk(value: unknown, w: SkeletonWalker, depth: number): unknown { w.nodes++ if (value === null || value === undefined) return String(value) const t = typeof value if (t !== 'object') return t // 'string' | 'number' | 'boolean' | 'bigint' | 'symbol' | 'function' const obj = value as object if (obj instanceof Date) return 'Date' if (obj instanceof RegExp) return 'RegExp' if (obj instanceof URL) return 'URL' if (obj instanceof Error) return 'Error' if (obj instanceof Promise) return 'Promise' if (w.seen.has(obj)) return '[circular]' if (depth >= w.opts.maxDepth) return '...' // Ancestor-path tracking (add/delete) so SHARED refs still expand and only // true cycles collapse to '[circular]'. w.seen.add(obj) try { return walkObject(obj, w, depth) } finally { w.seen.delete(obj) } } function walkObject(obj: object, w: SkeletonWalker, depth: number): unknown { if (Array.isArray(obj)) return walkArraySkeleton(obj, w, depth) if (ArrayBuffer.isView(obj)) return obj.constructor?.name ?? 'TypedArray' if (isMapLike(obj)) return walkMapSkeleton(obj, w, depth) if (isSetLike(obj)) return walkSetSkeleton(obj, w, depth) return walkPlainObject(obj, w, depth) } function walkArraySkeleton(arr: unknown[], w: SkeletonWalker, depth: number): unknown[] { const items = w.opts.excludeFunctions ? arr.filter(item => typeof item !== 'function') : arr if (items.length === 0) return [] const first = walk(items[0], w, depth + 1) return items.length > 1 ? [first, `+${items.length - 1} more`] : [first] } function walkMapSkeleton(map: Map, w: SkeletonWalker, depth: number): unknown { const first = map.entries().next().value as [unknown, unknown] | undefined if (!first) return `Map(0)` return { [`Map(${map.size})`]: { key: walk(first[0], w, depth + 1), value: walk(first[1], w, depth + 1), }, } } function walkSetSkeleton(set: Set, w: SkeletonWalker, depth: number): unknown { const first = set[Symbol.iterator]().next().value return first === undefined ? `Set(0)` : { [`Set(${set.size})`]: walk(first, w, depth + 1), } } function walkPlainObject(obj: object, w: SkeletonWalker, depth: number): Record { const proto = Object.getPrototypeOf(obj) const className = proto && proto !== Object.prototype ? (proto.constructor?.name as string | undefined) : undefined const out: Record = {} if (className && className !== 'Object') out.$class = className const keys = Object.keys(obj).filter(key => !isExcludedKey(key, w.opts)) const cap = Math.min(keys.length, w.opts.maxProps) for (let i = 0; i < cap; i++) walkPlainObjectKey(obj, keys[i], w, depth, out) if (keys.length > cap) out['...'] = `+${keys.length - cap} more props` return out } function walkPlainObjectKey(obj: object, key: string, w: SkeletonWalker, depth: number, out: Record): void { let v: unknown try { v = (obj as Record)[key] } catch { out[key] = 'getter-error' return } if (w.opts.excludeFunctions && typeof v === 'function') return out[key] = walk(v, w, depth + 1) }