ivue 1.6.1 → 2.0.0

package/README.md

@@ -1,47 +1,185 @@
-## ivue – Infinite Vue     [![npm](https://img.shields.io/npm/v/ivue.svg)](https://www.npmjs.com/package/ivue) [![build status](https://github.com/infinite-system/ivue/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/infinite-system/ivue/actions/workflows/ci.yml)
+<p align="center">
+  <a href="https://ivue.dev/">
+    <picture>
+      <source media="(prefers-color-scheme: dark)" srcset="docs_v2/public/brand-lockup-dark.png">
+      <img src="docs_v2/public/brand-lockup-light.png" alt="ivue — Infinite Vue" width="340">
+    </picture>
+  </a>
+</p>
 
-## About
+<h3 align="center">Plain classes. Full reactivity.<br>Infinite scalability. One kilobyte.</h3>
 
-`ivue` is a TypeScript class based composable architecture for Vue 3, that unlocks infinite scalability for Vue 3 based apps. It allows you to extend regular Vue 3 in a simple and elegant way.
+<p align="center">
+  <a href="https://www.npmjs.com/package/ivue"><img src="https://img.shields.io/npm/v/ivue.svg" alt="npm"></a>
+  <a href="https://github.com/infinite-system/ivue/actions/workflows/ci.yml"><img src="https://github.com/infinite-system/ivue/actions/workflows/ci.yml/badge.svg?branch=main" alt="build status"></a>
+</p>
 
-## Features
-&ndash; Simple & Elegant Architecture<br />
-&ndash; Extend Classes aligned with TypeScript Class design<br />
-&ndash; Extend Props Defaults<br />
-&ndash; Extend Emits<br />
-&ndash; Extend Slots<br />
-&ndash; Extend Components<br />
-&ndash; Improves DX by elegantly dealing with `.value` in the background<br />
-&ndash; Can be used both as a Store and a View Model for Components<br />
-&ndash; Zero dependencies except Vue 3<br />
+<p align="center">
+  <strong>Docs: <a href="https://ivue.dev/">ivue.dev</a></strong>
+</p>
 
-## What is ivue?
-## `ivue` is
+ivue builds Vue 3 reactivity out of plain TypeScript classes. Real
+inheritance, real encapsulation, real polymorphism — on ordinary objects,
+with nothing paid until first access. The whole engine is **1.1kb gzipped**
+with zero dependencies.
 
-&ndash;&nbsp; Simple like Options API<br />
-&ndash;&nbsp; Flexible like Composition API<br />
-&ndash;&nbsp; Extensible like TypeScript Class API<br />
-&ndash;&nbsp; Robust, Minimal, Opaque & Unobtrusive<br />
-&ndash;&nbsp; Pure Object Oriented Reactivity System based on Vue 3 Composition API<br />
-&ndash;&nbsp; 100% Vue 3 Compatible<br />
-&ndash;&nbsp; 100% Test Covered<br />
-&ndash;&nbsp; 100% Type Safe<br />
-&ndash;&nbsp; Production Ready<br />
-&ndash;&nbsp; Just <code>1.1kb</code> gzipped!<br />
-&ndash;&nbsp; 100% VSCode / Intellij IDE Auto-complete Intellisense<br />
+- **Native class API** — `extends`, `super`, getters, setters, private
+  fields. Real inheritance, encapsulation and polymorphism, all reactive.
+- **Zero-cost creation** — instances are plain objects. A million of them
+  take 22 ms — 6 to 132× faster than the alternatives.
+- **One kilobyte** — 1.1kb gzipped, zero dependencies, 100% test coverage.
+  Stripped to the load-bearing core — an API you can hold in your head.
+- **Store or ViewModel** — the same class serves as a global store, a
+  component ViewModel, or a domain model. One mental model everywhere.
+- **Composition API, fully compatible** — composables plug in through
+  `$`-getters. The entire Vue ecosystem works inside your classes.
+- **TypeScript first** — writable ref-getters, fully typed instances,
+  precise inference. The type system shaped the engine's design.
 
+## Getting started
 
+```sh
+npm i ivue vue
+```
 
-`ivue` is a powerful tool because it fully aligns itself with JavaScript / TypeScript Class API.
+## Built for humans and AI
 
-`ivue` gives you a class based Composable capabilities with Inheritance and all the power of TypeScript Classes.
+ivue ships with an [Operating Manual](https://ivue.dev/guide/standard) —
+the complete authoring standard as annotated templates, rules, and a review
+checklist. It reads as documentation and works as a drop-in skill for AI
+coding agents, so generated code follows the same standard your team writes:
 
-`ivue` mitigates the downsides of both Composition API and Options API, uses only their strengths and brings back Object Oriented Programming to allow the development of complex and scalable apps.
+```sh
+npx ivue skill        # installs .claude/skills/ivue/SKILL.md, version-locked
+npx ivue skill --all  # + Codex/Cursor/Copilot where already in use
+```
 
-`ivue` is fully interoperable with Composition API and does not work against, but rather with it, so you can use all of ecosystems composables seamlessly.
+### Usage
 
-`ivue` also offers a set of functions and utility types to make extensible & exportable props defaults, extensible emits and extensible slots possible.
+```ts
+import { Reactive } from 'ivue';
+import { ref } from 'vue';
 
-## Full Documentation
+class $Counter {
+  get count() {
+    return ref(0)
+  }
+  get double() {
+    return this.count.value * 2 // plain getter — derives on read
+  }
+  increment() {
+    this.count.value++
+  }
+}
 
-See: https://infinite-system.github.io/ivue/
+export namespace Counter {
+  export const $Class = $Counter; // raw — children `extends` this
+  export let Class = Reactive($Class); // reactive — you `new` this
+  export type Instance = typeof Class.Instance; // the unwrapping-surface type
+}
+```
+
+In a component:
+
+```vue
+<script setup lang="ts">
+import { Counter } from './Counter';
+
+const counter = new Counter.Class();
+
+// the state destructure — every Ref the template touches, unwrapped uniformly
+const { count } = counter;
+</script>
+
+<template>
+  <button @click="counter.increment()">{{ count }} · double {{ counter.double }}</button>
+</template>
+```
+
+Full walkthrough: [Getting Started](https://ivue.dev/guide/getting-started).
+
+## Hard problems, solved together
+
+Each of these sank earlier class-reactivity attempts. ivue ships all of them
+as one coherent design:
+
+- **Bound methods** — `this.method` is always correct, always the same reference.
+- **Reactive inheritance** — deep `super.x.value` chains resolve level-safe.
+- **Development parity** — the same class identity, direct binding, and engine branches in development and production.
+- **Circular import immunity** — the namespace pattern resolves mutual references in any load order.
+- **Writable getter types** — ref-returning getters type as writable; instances fully inferred.
+- **Deterministic teardown** — `$watch` scopes per instance, `$stopEffects()` cleans up.
+- **Minimal memory footprint** — derivations are shared prototype getters, not per-instance allocations.
+- **Hot paths** — reads hoist to native ref speed with one line where it matters.
+
+## One idea, carried through
+
+`Reactive()` transforms a class **once**. A getter returning `ref()` becomes
+state: created on first touch, cached, stable forever. A plain getter stays
+plain and re-derives on every read — reactive with zero allocation. Methods
+bind themselves once, to the right `this`. Instances stay ordinary objects:
+no proxy wraps them, no work happens at construction.
+
+Inheritance, teardown, development parity, speed — consequences of that one move.
+
+Composables plug straight in — the entire Vue ecosystem works inside your
+classes:
+
+```ts
+import { useMouse } from '@vueuse/core';
+
+class $Pointer {
+  private get $mouse() {
+    return useMouse() // created once, encapsulated
+  }
+  get x() {
+    return this.$mouse.x
+  }
+  get y() {
+    return this.$mouse.y
+  }
+}
+```
+
+## The numbers
+
+Measured, not promised — method and live in-browser benchmarks in
+[the docs](https://ivue.dev/guide/benchmarks).
+
+| creating 1,000,000 instances | time | ivue is |
+| --- | --- | --- |
+| **ivue `new Class()`** | **21.7 ms** | the baseline |
+| composable factory | 139 ms | **6.4× faster** |
+| native `reactive()` | 470 ms | **22× faster** |
+
+| memory heap at 100,000 live instances | per instance | 100k total |
+| --- | --- | --- |
+| **ivue class, 30 getters** | **3.7 KB** | 364 MB |
+| composable, 30 closures | 8.0 KB | 781 MB |
+| `reactive()`, fields + getters | 10.4 KB | 1.02 GB |
+| composable, 30 computeds | 19.7 KB | 1.93 GB |
+
+Taken all the way down: a fully reactive spreadsheet model holding
+**20,000,000 live cells at 4.7 bytes each** — 8.5× below the plain-object
+floor — because in ivue, everything costs proportional to what's *observed*,
+nothing costs proportional to what *exists*.
+
+## A note on the size
+
+The complete engine is **1.1kb gzipped**: lazy prototype transformation,
+bound methods, inheritance, lifecycle ownership, and the public utilities.
+Development uses that same engine without a second hot-update execution path.
+
+> *Perfection is achieved, not when there is nothing more to add, but when
+> there is nothing left to take away.* — Antoine de Saint-Exupéry
+
+## Documentation
+
+Full guide, principles, live benchmarks, advanced examples (a 1,000,000-row
+virtual scroller, a 20,000,000-cell flyweight grid, production-grade Quasar
+field components), and the API reference:
+**https://ivue.dev/**
+
+## License
+
+[MIT](./LICENSE)

package/bin/ivue.mjs

@@ -0,0 +1,152 @@
+#!/usr/bin/env node
+/**
+ * ivue CLI.
+ *
+ *   npx ivue skill [--force]
+ *
+ * Installs the operating manual — the same document that renders as the
+ * docs' Standard page — into ./.claude/skills/ivue/SKILL.md, where Claude
+ * Code (and compatible agents) pick it up as a skill. The copy comes from
+ * the installed package, so the manual always matches the engine version
+ * the project actually runs.
+ */
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const packageRoot = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+const [command, ...flags] = process.argv.slice(2);
+
+function fail(message) {
+  console.error(`ivue: ${message}`);
+  process.exit(1);
+}
+
+if (command !== 'skill') {
+  console.log(`ivue — commands:
+
+  npx ivue skill [targets] [--force]
+
+  Installs the ivue operating manual for coding agents. Targets:
+    (none) / --claude   .claude/skills/ivue/SKILL.md
+    --cursor            .cursor/rules/ivue.mdc
+    --copilot           .github/instructions/ivue.instructions.md
+    --agents / --codex  a managed section in AGENTS.md (Codex CLI,
+                        Windsurf, Gemini CLI and others read this file)
+    --all               Claude + every vendor whose footprint exists
+                        (.cursor/, .github/, AGENTS.md) — creates nothing new
+  --force overwrites locally modified copies.`);
+  process.exit(command === undefined || command === 'help' ? 0 : 1);
+}
+
+const force = flags.includes('--force');
+const version = JSON.parse(
+  readFileSync(join(packageRoot, 'package.json'), 'utf8'),
+).version;
+
+// published packages carry skills/; the repo itself carries .claude/skills/
+const sourcePath = [
+  join(packageRoot, 'skills', 'ivue', 'SKILL.md'),
+  join(packageRoot, '.claude', 'skills', 'ivue', 'SKILL.md'),
+].find(existsSync);
+if (!sourcePath) fail('SKILL.md not found in the installed package.');
+
+const skillText = readFileSync(sourcePath, 'utf8');
+// the manual's body, without the Claude skill frontmatter
+const skillBody = skillText.replace(/^---\n[\s\S]*?\n---\n+/, '');
+const skillDescription =
+  /description:\s*([^\n]+)/.exec(skillText)?.[1] ??
+  'The ivue operating manual.';
+
+/** Write one target idempotently; refuse to clobber local edits sans --force. */
+function install(relativePath, content, label) {
+  const targetPath = join(process.cwd(), relativePath);
+  if (existsSync(targetPath)) {
+    const existing = readFileSync(targetPath, 'utf8');
+    if (existing === content) {
+      console.log(`ivue: ${label} already up to date (ivue v${version}).`);
+      return;
+    }
+    if (!force) {
+      fail(
+        `${relativePath} exists and differs from ivue v${version}'s copy.\n` +
+          '      Re-run with --force to overwrite it.',
+      );
+    }
+  }
+  mkdirSync(dirname(targetPath), { recursive: true });
+  writeFileSync(targetPath, content);
+  console.log(`ivue: ${label} installed at ${relativePath} (ivue v${version}).`);
+}
+
+// Explicit flags always install (creating the folder is the point).
+// --all is detect-and-equip: vendor targets only where their footprint
+// already exists — it never scaffolds a tool you don't use. Claude is the
+// native format and installs in every mode.
+const wantAll = flags.includes('--all');
+const detected = (marker) => existsSync(join(process.cwd(), marker));
+const skipped = (label, marker, flag) =>
+  console.log(`ivue: ${label} skipped — no ${marker} here (pass ${flag} to create it).`);
+
+const wantCursor = flags.includes('--cursor') || (wantAll && detected('.cursor'));
+const wantCopilot = flags.includes('--copilot') || (wantAll && detected('.github'));
+const wantAgents =
+  flags.includes('--agents') ||
+  flags.includes('--codex') || // Codex CLI reads AGENTS.md — same target
+  (wantAll && detected('AGENTS.md'));
+const wantClaude =
+  wantAll ||
+  flags.includes('--claude') ||
+  (!flags.includes('--cursor') &&
+    !flags.includes('--copilot') &&
+    !flags.includes('--agents') &&
+    !flags.includes('--codex'));
+
+if (wantClaude) {
+  install('.claude/skills/ivue/SKILL.md', skillText, 'Claude skill');
+}
+if (wantAll && !wantCursor) skipped('Cursor rule', '.cursor/', '--cursor');
+if (wantAll && !wantCopilot) skipped('Copilot instructions', '.github/', '--copilot');
+if (wantAll && !wantAgents) skipped('AGENTS.md section', 'AGENTS.md', '--agents');
+if (wantCursor) {
+  install(
+    '.cursor/rules/ivue.mdc',
+    `---\ndescription: ${skillDescription}\nglobs:\nalwaysApply: false\n---\n\n${skillBody}`,
+    'Cursor rule',
+  );
+}
+if (wantCopilot) {
+  install(
+    '.github/instructions/ivue.instructions.md',
+    `---\napplyTo: '**/*.{ts,tsx,vue}'\n---\n\n${skillBody}`,
+    'Copilot instructions',
+  );
+}
+if (wantAgents) {
+  // AGENTS.md is shared and user-owned — manage only a marked section.
+  const startMarker = '<!-- ivue:skill:start -->';
+  const endMarker = '<!-- ivue:skill:end -->';
+  const section = `${startMarker}\n<!-- managed by \`npx ivue skill --agents\` — edits inside are overwritten -->\n\n${skillBody}\n${endMarker}`;
+  const agentsPath = join(process.cwd(), 'AGENTS.md');
+  if (existsSync(agentsPath)) {
+    const existing = readFileSync(agentsPath, 'utf8');
+    const start = existing.indexOf(startMarker);
+    const end = existing.indexOf(endMarker);
+    if (start !== -1 && end !== -1) {
+      const updated =
+        existing.slice(0, start) + section + existing.slice(end + endMarker.length);
+      if (updated === existing) {
+        console.log(`ivue: AGENTS.md section already up to date (ivue v${version}).`);
+      } else {
+        writeFileSync(agentsPath, updated);
+        console.log(`ivue: AGENTS.md section updated (ivue v${version}).`);
+      }
+    } else {
+      writeFileSync(agentsPath, existing.trimEnd() + '\n\n' + section + '\n');
+      console.log(`ivue: AGENTS.md section appended (ivue v${version}).`);
+    }
+  } else {
+    writeFileSync(agentsPath, section + '\n');
+    console.log(`ivue: AGENTS.md created (ivue v${version}).`);
+  }
+}

package/dist/Reactive.d.ts

@@ -0,0 +1,131 @@
+import { watch, watchEffect, type ExtractPropTypes, type Ref } from 'vue';
+/**
+ * Create a reactive class.
+ * @param targetClass The class to make reactive.
+ * @returns A reactive version of the class (the same class, transformed in place).
+ */
+export declare function Reactive<C extends new (...args: any) => any>(targetClass: C): ReactiveClass<C> & {
+    Instance: ReactiveInstance<InstanceType<C>>;
+};
+/**
+ * Vue props interface in defineComponent() style.
+ */
+export declare type VuePropsObject = Record<string, {
+    type: any;
+    default?: any;
+    required?: boolean;
+}>;
+/**
+ * Vue Props with default properties declared as existing and having values.
+ */
+export declare type VuePropsWithDefaults<T extends VuePropsObject> = {
+    [K in keyof T]: {
+        type: T[K]['type'];
+        default: T[K]['default'];
+        required?: boolean;
+    };
+};
+/**
+ * Determines if the value is a JavaScript Class.
+ * Note that class is a class function in JavaScript.
+ *
+ * @param val Any value
+ * @returns boolean If it's a JavaScript Class returns true
+ */
+export declare const isClass: (val: any) => boolean;
+/**
+ * Creates props with defaults in defineComponent() style.
+ *
+ * Merge defaults regular object with Vue types object
+ * declared in defineComponent() style.
+ *
+ * This is made so that the defaults can be declared "as they are"
+ * without requiring objects to be function callbacks returning an object.
+ *
+ * // You don't need to wrap objects in () => ({ nest: { nest :{} } })
+ * // You can just delcare them normally.
+ * const defaults = {
+ *    nest: {
+ *      nest
+ *    }
+ * }
+ *
+ * This function will create the Vue expected callbacks for Objects, Arrays & Classes
+ * but leave primitive properties and functions intact so that
+ * the final object is fully defineComponent() style compatible.
+ *
+ * The default cloner is the native `structuredClone` (zero-dependency, handles
+ * plain data, Map/Set/Date/typed arrays, circular refs). For defaults that
+ * contain class instances or functions — which `structuredClone` cannot clone —
+ * pass a `customCloner` such as lodash `cloneDeep`.
+ *
+ * @param defaults Regular object of default key -> values
+ * @param typedProps Props declared in defineComponent() style with type and possibly required declared, but without default
+ * @param customCloner Optional cloner used for object/array defaults (defaults to structuredClone)
+ * @returns Props declared in defineComponent() style with all properties having default property declared.
+ */
+export declare const propsWithDefaults: <T extends VuePropsObject>(defaults: Record<string, any>, typedProps: T, customCloner?: ((val: any) => any) | undefined) => VuePropsWithDefaults<T>;
+/**
+ * Type Utilities
+ */
+declare type GetterKeys<T> = {
+    [K in keyof T]: T[K] extends (...args: any[]) => any ? never : T[K] extends undefined ? never : K;
+}[keyof T];
+declare type GetterReturn<T, K extends keyof T> = T[K] extends (...args: any[]) => any ? never : T[K];
+declare type WritableComputedLike = Ref<any> & {
+    set: (...args: any[]) => any;
+};
+declare type IsWritableGetter<R> = R extends Ref<any> ? true : R extends WritableComputedLike ? true : false;
+declare type WritableGetters<T> = {
+    [K in GetterKeys<T> as IsWritableGetter<GetterReturn<T, K>> extends true ? K : never]-?: T[K];
+};
+export declare type ReactiveInstance<T> = T & WritableGetters<T> & {
+    /** Register a watcher in the instance's lazy effect scope (same signature as Vue `watch`). */
+    $watch: typeof watch;
+    /** Register a watchEffect in the instance's lazy effect scope (same signature as Vue `watchEffect`). */
+    $watchEffect: typeof watchEffect;
+    /** Stop the instance's effect scope and drop cached cells. */
+    $stopEffects: () => void;
+};
+export declare type ReactiveClass<C extends new (...args: any) => any> = new (...args: ConstructorParameters<C>) => ReactiveInstance<InstanceType<C>>;
+/**
+ * Component-authoring type utilities (types only — erased at build time).
+ * These complement `propsWithDefaults` for the params/defaults component
+ * architecture: object-declared emits, extensible slots, and precise
+ * handler-parameter extraction.
+ */
+/** Any JavaScript function of any type. */
+export declare type AnyFn = (...args: any[]) => any;
+/** Convert Record to Union Type. */
+export declare type RecordToUnion<T extends Record<string, any>> = T[keyof T];
+/** Gets object T property by key K. */
+export declare type ValueOf<T extends Record<any, any>, K extends keyof T> = T[K];
+/** Convert Union Type to Intersection Type. */
+export declare type UnionToIntersection<U> = (U extends any ? (k: U) => void : never) extends (k: infer I) => void ? I : never;
+/** Prefix keys of an interface T with a prefix P. */
+export declare type PrefixKeys<T, P extends string | undefined = undefined> = {
+    [K in Extract<keyof T, string> as P extends string ? `${P}${K}` : K]: T[K];
+};
+/** Extracts object-declared emit validators into the emit-function interface. */
+export declare type ExtractEmitTypes<T extends Record<string, any>> = UnionToIntersection<RecordToUnion<{
+    [K in keyof T]: (evt: K, ...args: Parameters<T[K]>) => void;
+}>>;
+/**
+ * Extract properties as all-assigned (non-optional) because every one of
+ * them carries a default.
+ */
+export declare type ExtractPropDefaultTypes<O> = {
+    [K in keyof O]: K extends keyof ExtractPropTypes<O> ? ExtractPropTypes<O>[K] : never;
+};
+/**
+ * Extend a slots interface T with prefixed 'before--' & 'after--' slots to
+ * create fully extensible wrapped components.
+ */
+export declare type ExtendSlots<T> = PrefixKeys<T, 'before--'> & T & PrefixKeys<T, 'after--'>;
+/** Get function arguments Parameters<F> parameter by index K. */
+export declare type FnParameter<F extends AnyFn, K extends number> = Parameters<F>[K];
+/** Get interface T property K's function arguments as Parameters. */
+export declare type IFnParameters<T extends Record<any, any>, K extends string> = Parameters<Required<Pick<T, K>>[K]>;
+/** Get interface T property P's function parameter by index K. */
+export declare type IFnParameter<T extends Record<any, any>, P extends keyof T, K extends number> = FnParameter<NonNullable<T[P]> extends AnyFn ? NonNullable<T[P]> : never, K>;
+export {};

package/dist/index.d.ts

@@ -1 +1 @@
-export * from './ivue';
+export * from './Reactive';