ivue 2.5.0 → 2.6.0

package/lib/__tests__/nestedProps.vitest.spec.ts

@@ -0,0 +1,153 @@
+import { describe, expect, it } from 'vitest';
+import { shallowReactive, shallowReadonly } from 'vue';
+import { nestedProps, type NestedPartial } from '../extras';
+
+type Knobs = {
+  wheel: { gain: number; follow: number };
+  touch: { gain: number; inertia: number; list: number[] };
+  label: string;
+};
+
+const defaults = (): Knobs => ({
+  wheel: { gain: 1, follow: 0.1 },
+  touch: { gain: 1.3, inertia: 30, list: [1, 2, 3] },
+  label: 'default'
+});
+
+describe('nestedProps', () => {
+  it('preserves null-prototype defaults, literal __proto__ keys and sparse arrays', () => {
+    const sparse = new Array<{ offset: number }>(2);
+    sparse[1] = { offset: 2 };
+    const bare = Object.assign(Object.create(null), { gain: 1 });
+    const literal = { ['__proto__']: { gain: 2 } };
+    const sharedDefaults = { scroll: { sparse, bare, literal } };
+    const filled = nestedProps({ scroll: {} }, sharedDefaults) as typeof sharedDefaults;
+
+    expect(Object.getPrototypeOf(filled.scroll.bare)).toBeNull();
+    expect(filled.scroll.bare).not.toBe(bare);
+    expect(Object.getPrototypeOf(filled.scroll.literal)).toBe(Object.prototype);
+    expect(Object.hasOwn(filled.scroll.literal, '__proto__')).toBe(true);
+    expect(filled.scroll.literal.__proto__).not.toBe(literal.__proto__);
+    expect(filled.scroll.sparse.length).toBe(2);
+    expect(0 in filled.scroll.sparse).toBe(false);
+    filled.scroll.sparse[1].offset = 9;
+    expect(sparse[1].offset).toBe(2);
+  });
+
+  it('copies missing default objects and arrays independently for each instance', () => {
+    const sharedDefaults = { scroll: { touch: { gain: 1, points: [{ offset: 2 }] }, steps: [1, 2] } };
+    const first = nestedProps({ scroll: {} }, sharedDefaults) as typeof sharedDefaults;
+    const second = nestedProps({ scroll: {} }, sharedDefaults) as typeof sharedDefaults;
+
+    first.scroll.touch.gain = 9;
+    first.scroll.touch.points[0].offset = 8;
+    first.scroll.steps.push(3);
+
+    expect(second).toEqual({ scroll: { touch: { gain: 1, points: [{ offset: 2 }] }, steps: [1, 2] } });
+    expect(sharedDefaults).toEqual(second);
+    expect(second.scroll.touch).not.toBe(sharedDefaults.scroll.touch);
+    expect(second.scroll.steps).not.toBe(sharedDefaults.scroll.steps);
+  });
+
+  it('preserves supplied containers and opaque default values when copying missing branches', () => {
+    class Tuning { gain = 9; }
+    const tuning = new Tuning();
+    const callback = () => 1;
+    const suppliedList = [7];
+    const supplied = { scroll: { list: suppliedList } };
+    const sharedDefaults = { scroll: { list: [1], touch: { tuning, callback, label: null } } };
+    const filled = nestedProps(supplied, sharedDefaults) as typeof sharedDefaults;
+
+    expect(filled).toBe(supplied);
+    expect(filled.scroll.list).toBe(suppliedList);
+    expect(filled.scroll.touch).not.toBe(sharedDefaults.scroll.touch);
+    expect(filled.scroll.touch.tuning).toBe(tuning);
+    expect(filled.scroll.touch.callback).toBe(callback);
+    expect(filled.scroll.touch.label).toBeNull();
+  });
+
+  it('fills a partial object from the defaults at every depth, in place, keeping every supplied leaf', () => {
+    const supplied: NestedPartial<Knobs> = { wheel: { gain: 2 }, label: 'mine' };
+    const props = nestedProps(supplied, defaults());
+    expect(props).toBe(supplied);
+    expect(props.wheel).toEqual({ gain: 2, follow: 0.1 });
+    expect(props.label).toBe('mine');
+    // A top-level prop is Vue's to default: never written here.
+    expect('touch' in props).toBe(false);
+  });
+
+  it('recurses through every plain-object level, filling only what is missing', () => {
+    const tree = { a: { b: { c: 9 }, e: 5 } };
+    const filled = nestedProps({ tree }, { tree: { a: { b: { c: 1, d: 2 }, e: 3, f: 4 } } });
+    expect(filled.tree).toBe(tree);
+    expect(filled.tree).toEqual({ a: { b: { c: 9, d: 2 }, e: 5, f: 4 } });
+  });
+
+  it('skips a top-level prop that is not a plain object on both sides, and fills a prototype-less default', () => {
+    const bareDefault = Object.create(null) as { z: number; y: number };
+    bareDefault.z = 1;
+    bareDefault.y = 2;
+    const props = { list: null as unknown as number[], label: 'mine', bare: { z: 5 }, fn: () => 1 };
+    const filled = nestedProps(props, { list: [1, 2], label: 'default', bare: bareDefault, fn: { a: 1 } });
+    expect(filled.list).toBeNull();
+    expect(filled.label).toBe('mine');
+    expect(filled.bare).toEqual({ z: 5, y: 2 });
+    expect(typeof filled.fn).toBe('function');
+  });
+
+  it('treats a nested undefined as absent and a nested null as a value', () => {
+    const props = nestedProps(
+      { wheel: { gain: undefined, follow: null } } as unknown as NestedPartial<Knobs>,
+      defaults()
+    );
+    expect(props.wheel.gain).toBe(1);
+    expect(props.wheel.follow).toBeNull();
+  });
+
+  it('takes arrays, class instances and functions whole, never merged', () => {
+    class Tuning {
+      gain = 9;
+    }
+    const tuning = new Tuning();
+    const props = nestedProps(
+      { touch: { list: [7] }, wheel: tuning } as unknown as NestedPartial<Knobs>,
+      defaults()
+    );
+    expect(props.touch.list).toEqual([7]);
+    expect(props.touch.inertia).toBe(30);
+    expect(props.wheel).toBe(tuning);
+    expect((props.wheel as unknown as Tuning).gain).toBe(9);
+    // An object supplied where the default is an array is kept as is.
+    const odd = nestedProps({ touch: { list: { 0: 7 } } } as unknown as NestedPartial<Knobs>, defaults());
+    expect(odd.touch.list).toEqual({ 0: 7 });
+    // A prototype-less object is plain too.
+    const bare = Object.create(null) as { gain: number };
+    bare.gain = 4;
+    const filled = nestedProps({ wheel: bare } as unknown as NestedPartial<Knobs>, defaults());
+    expect(filled.wheel).toBe(bare);
+    expect(filled.wheel.follow).toBe(0.1);
+  });
+
+  it('works through Vue’s shallow props proxy: the nested object is the parent’s and is filled directly', () => {
+    const wheel = { gain: 2 };
+    const props = shallowReadonly(shallowReactive({ wheel } as NestedPartial<Knobs>));
+    const filled = nestedProps(props, defaults());
+    expect(filled.wheel.follow).toBe(0.1);
+    expect(wheel).toEqual({ gain: 2, follow: 0.1 });
+  });
+
+  it('customCloner is the copy policy for default branches: identity shares them, structuredClone copies built-ins', () => {
+    const wheelDefault = { gain: 1, follow: 0.1 };
+    const first = nestedProps({} as NestedPartial<Knobs>, { wheel: wheelDefault } as Knobs);
+    expect(first.wheel).not.toBe(wheelDefault);
+    // The caller owns a fresh tree per instance and says so: no copy.
+    const owned = { list: [7] };
+    const identity = nestedProps({ touch: {} } as NestedPartial<Knobs>, { touch: owned } as unknown as Knobs, (value) => value);
+    expect(identity.touch.list).toBe(owned.list);
+    // structuredClone gives Date defaults their own copies.
+    const stamp = new Date(0);
+    const copied = nestedProps({ meta: {} } as { meta: { stamp?: Date } }, { meta: { stamp } }, structuredClone);
+    expect(copied.meta.stamp).not.toBe(stamp);
+    expect(copied.meta.stamp?.getTime()).toBe(0);
+  });
+});

package/lib/clone.ts

@@ -0,0 +1,21 @@
+/** Copy plain configuration containers; retain callbacks, constructors and
+ *  opaque objects by reference. Container trees must be acyclic. */
+export function clone<T>(value: T): T {
+  if (Array.isArray(value)) {
+    const copy = new Array(value.length);
+    for (let index = 0; index < value.length; index++) {
+      if (index in value) copy[index] = clone(value[index]);
+    }
+    return copy as T;
+  }
+  if (
+    value === null ||
+    typeof value !== 'object' ||
+    (value.constructor !== Object && value.constructor !== undefined)
+  ) return value;
+
+  // Preserve null prototypes and literal __proto__ keys without entry arrays.
+  const copy: Record<string, unknown> = { __proto__: Object.getPrototypeOf(value), ...value };
+  for (const key in copy) copy[key] = clone(copy[key]);
+  return copy as T;
+}

package/lib/extras.ts

@@ -8,3 +8,4 @@
  */
 export { Static, type ClassConstructor } from './Static';
 export { LazyShared } from './LazyShared';
+export { nestedProps, type NestedPartial, type NestedProps } from './nestedProps';

package/lib/nestedProps.ts

@@ -0,0 +1,126 @@
+/**
+ * `nestedProps(props, defaults)` — fill a nested object prop from its
+ * defaults, in place, so the class reads complete props at every depth.
+ *
+ * Vue resolves a prop's default only when the prop is ABSENT: pass
+ * `{ wheel: { gain: 2 } }` for a prop whose default is
+ * `{ wheel: { gain: 1, follow: 0.1 }, touch: { … } }` and the component
+ * receives exactly the object it was passed — `follow` and `touch` are
+ * gone. `propsWithDefaults` decides what the default IS and clones it per
+ * instance; it cannot reach inside a supplied object. The fill is possible
+ * at all because the defaults are a value the class owns — a compiler-only
+ * default has nothing to fill from.
+ *
+ * The semantics are lodash's `defaultsDeep` with arrays taken whole: for
+ * every prop whose value and default are both plain objects, each leaf the
+ * supplied object lacks is written into it from the default, recursively;
+ * a leaf it has is kept. Missing plain-object and array defaults are copied
+ * recursively so instances never share those mutable containers. Arrays
+ * are never merged; class instances and functions retain their identity. Vue's
+ * props proxy is shallow, so the nested objects are the parent's own and
+ * are written directly; the props object itself is untouched and returned.
+ *
+ * Call it once, at the seam where props enter the class:
+ *
+ *   constructor(props: Scroller.Props, public emit: Scroller.Emits) {
+ *     this.props = nestedProps(props, this.self.propsDefaults);
+ *   }
+ *
+ * The parent passes a stable object: a constant inline literal (Vue hoists
+ * it), a `ref`'s value, a store field. An object built anew on every
+ * parent render is a new, unfilled object each time.
+ *
+ * `customCloner` is the same policy knob `propsWithDefaults` has: it copies
+ * each default branch written into the props. The default, `clone`, copies
+ * plain containers and keeps callbacks, constructors and opaque objects by
+ * reference, so no two instances share a mutable default. Pass
+ * `structuredClone` when `Date`, `Map` or `Set` defaults need their own
+ * copies; pass the identity, `value => value`, only when the caller owns
+ * every default it passes — a fresh tree per instance, never a shared one.
+ *
+ * `NestedPartial<T>` is the matching declaration for the prop's type — the
+ * shape an author may pass — and `NestedProps<P, D>` the type of the
+ * filled props, where every key both sides carry as an object is complete.
+ *
+ * Ships from `ivue/extras` (not the reactive core) so the primary `ivue`
+ * entry stays minimal.
+ */
+
+import { clone } from './clone';
+
+/** Every key optional at every plain-object depth; arrays stay whole. */
+export type NestedPartial<T> = T extends readonly unknown[]
+  ? T
+  : T extends object
+    ? { [K in keyof T]?: NestedPartial<T[K]> }
+    : T;
+
+/** The filled props' type: a key both sides carry as a plain object is complete. */
+export type NestedProps<P, D> = {
+  [K in keyof P as K extends keyof D ? K : never]-?: NestedLeaf<
+    NonNullable<P[K]>,
+    D[K & keyof D]
+  >;
+} & {
+  [K in keyof P as K extends keyof D ? never : K]: P[K];
+};
+
+/** A value the fill takes whole: not a plain container. */
+type Opaque = Date | RegExp | Map<unknown, unknown> | Set<unknown> | ((...args: never[]) => unknown);
+
+type NestedLeaf<V, D> = V extends readonly unknown[]
+  ? V
+  : V extends Opaque
+    ? V
+    : V extends object
+    ? D extends readonly unknown[]
+      ? V
+      : D extends object
+        ? NestedProps<V, D>
+        : V
+    : V;
+
+type PlainObject = Record<PropertyKey, unknown>;
+
+/** A plain object — an object literal, `Object.create(null)`, or a reactive
+ *  proxy over either; not an array, a class instance or a function. A
+ *  `constructor` check, no prototype walk. */
+function isPlain(value: unknown): value is PlainObject {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    ((value as PlainObject).constructor === Object ||
+      (value as PlainObject).constructor === undefined)
+  );
+}
+
+/** Write every leaf `target` lacks from `defaults`, recursively; keep what
+ *  it has. `for…in` over the defaults: plain objects have no enumerable
+ *  prototype keys. */
+function fill(target: PlainObject, defaults: PlainObject, copy: (value: unknown) => unknown) {
+  for (const key in defaults) {
+    const value = target[key];
+    const fallback = defaults[key];
+    if (value === undefined) target[key] = copy(fallback);
+    else if (isPlain(value) && isPlain(fallback)) fill(value, fallback, copy);
+  }
+}
+
+/**
+ * Fill every nested object prop from its default, in place, and return
+ * the props typed as complete. Top-level props are Vue's to default and
+ * are never written.
+ */
+export function nestedProps<P extends object, D extends object>(
+  props: P,
+  defaults: D,
+  // Optional: the copy policy for default branches written into the props.
+  customCloner: (value: unknown) => unknown = clone
+): NestedProps<P, D> {
+  for (const key in defaults) {
+    const value = (props as PlainObject)[key];
+    const fallback = (defaults as PlainObject)[key];
+    if (isPlain(value) && isPlain(fallback)) fill(value, fallback, customCloner);
+  }
+  return props as unknown as NestedProps<P, D>;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "ivue",
-  "version": "2.5.0",
+  "version": "2.6.0",
   "description": "Infinite Vue – Class Based Architecture for Vue 3",
   "type": "module",
   "exports": {
@@ -22,6 +22,8 @@
   "types": "./dist/index.d.ts",
   "scripts": {
     "gate": "vite-node skills/ivue/ivue-standards-check.ts --",
+    "gate:docs": "node scripts/gate-docs.mjs",
+    "sweep:components": "NODE_PATH=$PWD/node_modules node docs_v2/scripts/component-sweep.cjs",
     "gate:house": "vite-node skills/ivue/ivue-house-gate.ts --",
     "gate:newsletter": "vite-node skills/ivue/ivue-generator-standard.ts -- --source-root newsletter --skip-list skills/ivue/ivue-standards-skip.json --test-glob 'newsletter/src/**/*.test.ts'",
     "dev": "vite demo --host",
@@ -41,9 +43,9 @@
     "bench:node-namespace": "vite-node experiments/node-namespace/benchmark.ts",
     "cypress": "cypress run --component",
     "cypress:headed": "cypress run --component --browser chrome --headed --no-exit",
-    "build": "tsc --version;tsc --p ./tsconfig.json && vite build",
+    "build": "tsc --version;tsc --p ./tsconfig.json && node scripts/build-lib.mjs",
     "build:demo": "tsc --p ./tsconfig.json && vite build demo",
-    "build:docs": "npm run sync:examples && npm run sync:releases && npm run sync:blog-index && node docs_v2/scripts/rss-generator.mjs && npm --prefix docs_v2 run build && npm run check:links && node docs_v2/scripts/check-related-posts.mjs",
+    "build:docs": "npm run gate:docs && npm run sync:examples && npm run sync:releases && npm run sync:blog-index && node docs_v2/scripts/rss-generator.mjs && npm --prefix docs_v2 run build && npm run check:links && node docs_v2/scripts/check-related-posts.mjs && node docs_v2/scripts/check-private-ban.mjs",
     "sync:releases": "node docs_v2/scripts/releases-page-generator.mjs",
     "sync:blog-index": "node docs_v2/scripts/blog-index-generator.mjs",
     "check:links": "node docs_v2/scripts/check-links.mjs",
@@ -60,7 +62,7 @@
     "release": "npm run build && npm publish",
     "sync:skill": "node -e \"const fs=require('fs');fs.mkdirSync('skills/ivue',{recursive:true});fs.copyFileSync('.claude/skills/ivue/SKILL.md','skills/ivue/SKILL.md')\"",
     "prepack": "npm run sync:skill",
-    "sync:examples": "node -e \"require('fs').copyFileSync('lib/Reactive.ts','examples/playground/src/ivue.ts')\"",
+    "sync:examples": "node scripts/sync-examples.mjs",
     "dev:playground": "vite examples/playground --host",
     "build:playground": "vite build examples/playground",
     "preview:playground": "vite preview examples/playground --host",
@@ -106,7 +108,9 @@
     "rollup-plugin-terser": "^7.0.2",
     "typescript": "^5.9.3",
     "vite": "^4.0.4",
+    "vite-node": "^2.0.5",
     "vite-plugin-dts": "^1.7.1",
+    "@microsoft/api-extractor": "7.33.8",
     "vite-plugin-dynamic-import": "^1.5.0",
     "vite-tsconfig-paths": "^4.3.2",
     "vitest": "^2.0.5",