mvc-kit 2.12.0 → 2.12.1

package/src/bindPublicMethods.test.ts

@@ -0,0 +1,126 @@
+import { describe, it, expect } from 'vitest';
+import { bindPublicMethods } from './bindPublicMethods';
+
+class Base {
+  value = 0;
+  increment() { this.value++; }
+  _private() { this.value += 100; }
+  get computed() { return this.value * 2; }
+}
+
+class Child extends Base {
+  greet() { return `hello ${this.value}`; }
+  increment() { this.value += 10; } // override
+}
+
+describe('bindPublicMethods', () => {
+  it('binds public methods so they work detached', () => {
+    const obj = new Base();
+    bindPublicMethods(obj);
+    const { increment } = obj;
+    increment();
+    expect(obj.value).toBe(1);
+  });
+
+  it('skips _-prefixed methods', () => {
+    const obj = new Base();
+    bindPublicMethods(obj);
+    // _private should NOT be an own property (still on prototype)
+    expect(Object.getOwnPropertyDescriptor(obj, '_private')?.value).toBeUndefined();
+  });
+
+  it('skips getters', () => {
+    const obj = new Base();
+    bindPublicMethods(obj);
+    // computed should still be a getter, not a bound function
+    expect(obj.computed).toBe(0);
+    obj.value = 5;
+    expect(obj.computed).toBe(10);
+  });
+
+  it('most-derived override wins in inheritance chains', () => {
+    const obj = new Child();
+    bindPublicMethods(obj);
+    const { increment } = obj;
+    increment(); // should use Child's override (+10), not Base's (+1)
+    expect(obj.value).toBe(10);
+  });
+
+  it('binds subclass methods', () => {
+    const obj = new Child();
+    bindPublicMethods(obj);
+    const { greet } = obj;
+    expect(greet()).toBe('hello 0');
+  });
+
+  it('is a no-op for classes with no public methods', () => {
+    class Empty {
+      _internal() {}
+    }
+    const obj = new Empty();
+    bindPublicMethods(obj);
+    // No own method properties should be added
+    const ownKeys = Object.getOwnPropertyNames(obj).filter(
+      k => typeof (obj as any)[k] === 'function',
+    );
+    expect(ownKeys).toHaveLength(0);
+  });
+
+  it('stopPrototype limits which prototypes are walked', () => {
+    class GrandParent {
+      gpMethod() { return 'gp'; }
+    }
+    class Parent extends GrandParent {
+      parentMethod() { return 'parent'; }
+    }
+    class Leaf extends Parent {
+      leafMethod() { return 'leaf'; }
+    }
+
+    const obj = new Leaf();
+    // Stop at GrandParent.prototype — should NOT bind gpMethod
+    bindPublicMethods(obj, GrandParent.prototype);
+    const { leafMethod, parentMethod } = obj;
+    expect(leafMethod()).toBe('leaf');
+    expect(parentMethod()).toBe('parent');
+    // gpMethod should NOT be an own property
+    expect(Object.getOwnPropertyDescriptor(obj, 'gpMethod')).toBeUndefined();
+  });
+
+  it('caches results across instances of the same class', () => {
+    const obj1 = new Child();
+    const obj2 = new Child();
+    bindPublicMethods(obj1);
+    bindPublicMethods(obj2);
+    // Both should work — cache serves second instance
+    const { increment: inc1 } = obj1;
+    const { increment: inc2 } = obj2;
+    inc1();
+    inc2();
+    expect(obj1.value).toBe(10);
+    expect(obj2.value).toBe(10);
+    // They should be independent bindings
+    expect(obj1.increment).not.toBe(obj2.increment);
+  });
+
+  it('exclude parameter skips specified method names', () => {
+    class WithProtected {
+      value = 0;
+      publicMethod() { this.value = 1; }
+      protectedMethod() { this.value = 99; }
+      anotherProtected() { this.value = 99; }
+    }
+    const exclude = new Set(['protectedMethod', 'anotherProtected']);
+    const obj = new WithProtected();
+    bindPublicMethods(obj, Object.prototype, exclude);
+
+    // publicMethod should be bound (own property)
+    const { publicMethod } = obj;
+    publicMethod();
+    expect(obj.value).toBe(1);
+
+    // excluded methods should NOT be own properties
+    expect(Object.getOwnPropertyDescriptor(obj, 'protectedMethod')).toBeUndefined();
+    expect(Object.getOwnPropertyDescriptor(obj, 'anotherProtected')).toBeUndefined();
+  });
+});

package/src/bindPublicMethods.ts

@@ -0,0 +1,48 @@
+import { walkPrototypeChain } from './walkPrototypeChain';
+
+/** Cached list of bindable method keys + prototype functions per class. */
+const methodCache = new WeakMap<Function, Array<{ key: string; fn: Function }>>();
+
+/**
+ * Auto-binds all public methods on the instance so they can be passed
+ * as callbacks without losing `this` context (point-free style).
+ *
+ * Walks the prototype chain from the instance up to (but not including)
+ * `stopPrototype` (defaults to `Object.prototype`). Skips `_`-prefixed
+ * methods, getters/setters, and any keys in the `exclude` set.
+ * Most-derived version wins for override chains.
+ *
+ * Results are cached per class constructor in a WeakMap — subsequent
+ * instances of the same class skip the prototype walk entirely.
+ *
+ * @param exclude Keys to skip (e.g. protected/internal methods that should
+ *   not be bound). Must be the same set for all instances of a given class
+ *   since the result is cached by constructor.
+ */
+export function bindPublicMethods(
+  instance: object,
+  stopPrototype: object = Object.prototype,
+  exclude?: ReadonlySet<string>,
+): void {
+  const ctor = instance.constructor;
+  let methods = methodCache.get(ctor);
+
+  if (!methods) {
+    methods = [];
+    const seen = new Set<string>();
+    walkPrototypeChain(instance, stopPrototype, (key, desc) => {
+      if (seen.has(key)) return;
+      seen.add(key);
+      if (desc.get || desc.set) return;
+      if (typeof desc.value !== 'function') return;
+      if (key.startsWith('_')) return;
+      if (exclude?.has(key)) return;
+      methods!.push({ key, fn: desc.value });
+    });
+    methodCache.set(ctor, methods);
+  }
+
+  for (let i = 0; i < methods.length; i++) {
+    (instance as any)[methods[i].key] = methods[i].fn.bind(instance);
+  }
+}

package/src/env.d.ts

@@ -0,0 +1,5 @@
+declare global {
+  var __MVC_KIT_DEV__: boolean | undefined;
+}
+
+export {};

package/src/errors.test.ts

@@ -0,0 +1,155 @@
+import { describe, it, expect } from 'vitest';
+import { HttpError, isAbortError, classifyError } from './errors';
+import type { AppError } from './errors';
+
+describe('HttpError', () => {
+  it('creates with status and default message', () => {
+    const err = new HttpError(404);
+    expect(err.status).toBe(404);
+    expect(err.message).toBe('HTTP 404');
+    expect(err.name).toBe('HttpError');
+    expect(err).toBeInstanceOf(Error);
+  });
+
+  it('creates with status and custom message', () => {
+    const err = new HttpError(401, 'Unauthorized');
+    expect(err.status).toBe(401);
+    expect(err.message).toBe('Unauthorized');
+  });
+});
+
+describe('isAbortError', () => {
+  it('returns true for AbortError DOMException', () => {
+    const err = new DOMException('The operation was aborted', 'AbortError');
+    expect(isAbortError(err)).toBe(true);
+  });
+
+  it('returns false for other DOMExceptions', () => {
+    const err = new DOMException('msg', 'NotFoundError');
+    expect(isAbortError(err)).toBe(false);
+  });
+
+  it('returns false for regular Error', () => {
+    expect(isAbortError(new Error('AbortError'))).toBe(false);
+  });
+
+  it('returns false for non-Error values', () => {
+    expect(isAbortError('AbortError')).toBe(false);
+    expect(isAbortError(null)).toBe(false);
+    expect(isAbortError(undefined)).toBe(false);
+  });
+});
+
+describe('classifyError', () => {
+  it('classifies AbortError → abort', () => {
+    const err = new DOMException('aborted', 'AbortError');
+    const result = classifyError(err);
+    expect(result.code).toBe('abort');
+    expect(result.original).toBe(err);
+  });
+
+  it('classifies HttpError 401 → unauthorized', () => {
+    const err = new HttpError(401, 'Unauthorized');
+    const result = classifyError(err);
+    expect(result).toEqual<AppError>({
+      code: 'unauthorized',
+      message: 'Unauthorized',
+      status: 401,
+      original: err,
+    });
+  });
+
+  it('classifies HttpError 403 → forbidden', () => {
+    const result = classifyError(new HttpError(403));
+    expect(result.code).toBe('forbidden');
+    expect(result.status).toBe(403);
+  });
+
+  it('classifies HttpError 404 → not_found', () => {
+    const result = classifyError(new HttpError(404));
+    expect(result.code).toBe('not_found');
+    expect(result.status).toBe(404);
+  });
+
+  it('classifies HttpError 422 → validation', () => {
+    const result = classifyError(new HttpError(422));
+    expect(result.code).toBe('validation');
+    expect(result.status).toBe(422);
+  });
+
+  it('classifies HttpError 429 → rate_limited', () => {
+    const result = classifyError(new HttpError(429));
+    expect(result.code).toBe('rate_limited');
+    expect(result.status).toBe(429);
+  });
+
+  it('classifies HttpError 500 → server_error', () => {
+    const result = classifyError(new HttpError(500));
+    expect(result.code).toBe('server_error');
+    expect(result.status).toBe(500);
+  });
+
+  it('classifies HttpError 503 → server_error', () => {
+    const result = classifyError(new HttpError(503));
+    expect(result.code).toBe('server_error');
+    expect(result.status).toBe(503);
+  });
+
+  it('classifies HttpError with unknown status → unknown', () => {
+    const result = classifyError(new HttpError(418));
+    expect(result.code).toBe('unknown');
+    expect(result.status).toBe(418);
+  });
+
+  it('classifies Response object by status', () => {
+    const res = new Response(null, { status: 404, statusText: 'Not Found' });
+    const result = classifyError(res);
+    expect(result.code).toBe('not_found');
+    expect(result.status).toBe(404);
+    expect(result.message).toBe('Not Found');
+    expect(result.original).toBe(res);
+  });
+
+  it('classifies Response with empty statusText', () => {
+    const res = new Response(null, { status: 500 });
+    const result = classifyError(res);
+    expect(result.code).toBe('server_error');
+    expect(result.message).toBe('HTTP 500');
+  });
+
+  it('classifies TypeError with "fetch" → network', () => {
+    const err = new TypeError('Failed to fetch');
+    const result = classifyError(err);
+    expect(result.code).toBe('network');
+    expect(result.original).toBe(err);
+  });
+
+  it('classifies TimeoutError → timeout', () => {
+    const err = new Error('Operation timed out');
+    err.name = 'TimeoutError';
+    const result = classifyError(err);
+    expect(result.code).toBe('timeout');
+    expect(result.original).toBe(err);
+  });
+
+  it('classifies generic Error → unknown', () => {
+    const err = new Error('Something broke');
+    const result = classifyError(err);
+    expect(result.code).toBe('unknown');
+    expect(result.message).toBe('Something broke');
+    expect(result.original).toBe(err);
+  });
+
+  it('classifies non-Error value → unknown', () => {
+    const result = classifyError('string error');
+    expect(result.code).toBe('unknown');
+    expect(result.message).toBe('string error');
+    expect(result.original).toBe('string error');
+  });
+
+  it('classifies null → unknown', () => {
+    const result = classifyError(null);
+    expect(result.code).toBe('unknown');
+    expect(result.message).toBe('null');
+  });
+});

package/src/errors.ts

@@ -0,0 +1,133 @@
+/**
+ * Canonical application error shape for consistent error handling.
+ */
+export interface AppError {
+  code:
+    | 'unauthorized'
+    | 'forbidden'
+    | 'not_found'
+    | 'validation'
+    | 'rate_limited'
+    | 'server_error'
+    | 'network'
+    | 'timeout'
+    | 'abort'
+    | 'unknown';
+  message: string;
+  status?: number;
+  original?: unknown;
+}
+
+/**
+ * Typed HTTP error for services to throw.
+ */
+export class HttpError extends Error {
+  constructor(
+    public readonly status: number,
+    message?: string
+  ) {
+    super(message ?? `HTTP ${status}`);
+    this.name = 'HttpError';
+  }
+}
+
+/**
+ * Guard for AbortError — the most-repeated check in async ViewModels.
+ * Uses duck-typing so the core lib doesn't require DOM types.
+ */
+export function isAbortError(error: unknown): boolean {
+  return error instanceof Error && error.name === 'AbortError';
+}
+
+function classifyHttpStatus(
+  status: number
+): AppError['code'] {
+  if (status === 401) return 'unauthorized';
+  if (status === 403) return 'forbidden';
+  if (status === 404) return 'not_found';
+  if (status === 422) return 'validation';
+  if (status === 429) return 'rate_limited';
+  if (status >= 500) return 'server_error';
+  return 'unknown';
+}
+
+function isResponseLike(value: unknown): value is { status: number; statusText: string } {
+  return (
+    typeof value === 'object' &&
+    value !== null &&
+    typeof (value as Record<string, unknown>).status === 'number' &&
+    typeof (value as Record<string, unknown>).statusText === 'string' &&
+    !(value instanceof Error)
+  );
+}
+
+/**
+ * Maps raw errors to a canonical AppError shape.
+ */
+export function classifyError(error: unknown): AppError {
+  // AbortError (fetch cancelled / DOMException)
+  if (error instanceof Error && error.name === 'AbortError') {
+    return {
+      code: 'abort',
+      message: 'Request was aborted',
+      original: error,
+    };
+  }
+
+  // HttpError (thrown by services)
+  if (error instanceof HttpError) {
+    return {
+      code: classifyHttpStatus(error.status),
+      message: error.message,
+      status: error.status,
+      original: error,
+    };
+  }
+
+  // Raw Response object (duck-typed: has status + statusText, is not an Error)
+  if (isResponseLike(error)) {
+    return {
+      code: classifyHttpStatus(error.status),
+      message: error.statusText || `HTTP ${error.status}`,
+      status: error.status,
+      original: error,
+    };
+  }
+
+  // Network error (fetch failure)
+  if (
+    error instanceof TypeError &&
+    error.message.toLowerCase().includes('fetch')
+  ) {
+    return {
+      code: 'network',
+      message: error.message,
+      original: error,
+    };
+  }
+
+  // Timeout error
+  if (error instanceof Error && error.name === 'TimeoutError') {
+    return {
+      code: 'timeout',
+      message: error.message,
+      original: error,
+    };
+  }
+
+  // Generic Error fallback
+  if (error instanceof Error) {
+    return {
+      code: 'unknown',
+      message: error.message,
+      original: error,
+    };
+  }
+
+  // Non-Error fallback
+  return {
+    code: 'unknown',
+    message: String(error),
+    original: error,
+  };
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+// Types
+export type {
+  Listener,
+  Updater,
+  Subscribable,
+  Disposable,
+  Initializable,
+  ValidationErrors,
+  TaskState,
+  EventSource,
+  EventPayload,
+} from './types';
+
+export type { AsyncMethodKeys } from './ViewModel';
+export type { ResourceAsyncMethodKeys } from './Resource';
+
+// Core primitives
+export { ViewModel } from './ViewModel';
+export { Model } from './Model';
+export { Collection } from './Collection';
+export { PersistentCollection } from './PersistentCollection';
+export { Resource } from './Resource';
+export { Controller } from './Controller';
+export { Service } from './Service';
+export { EventBus } from './EventBus';
+export { Channel } from './Channel';
+export type { ChannelStatus } from './Channel';
+export { Trackable } from './Trackable';
+
+// Composable helpers
+export { Sorting } from './Sorting';
+export type { SortDescriptor } from './Sorting';
+export { Pagination } from './Pagination';
+export { Selection } from './Selection';
+export { Feed } from './Feed';
+export type { FeedPage } from './Feed';
+export { Pending } from './Pending';
+export type { PendingOperation, PendingEntry } from './Pending';
+
+// Error handling utilities
+export type { AppError } from './errors';
+export { HttpError, isAbortError, classifyError } from './errors';
+
+// Utilities
+export { bindPublicMethods } from './bindPublicMethods';
+export { produceDraft, resolveDraftUpdater } from './produceDraft';
+
+// Singleton registry
+export { singleton, hasSingleton, teardown, teardownAll } from './singleton';

package/src/produceDraft.md

@@ -0,0 +1,90 @@
+# produceDraft
+
+Standalone copy-on-write draft utility. Creates a proxy of a frozen state object, runs a mutator function, and returns only the changed top-level keys as a `Partial`. Used internally by `ViewModel.set()` and `Model.set()` for draft mode, but also exported for standalone use.
+
+---
+
+## API
+
+```typescript
+import { produceDraft } from 'mvc-kit';
+
+function produceDraft<S extends object>(
+  state: Readonly<S>,
+  mutator: (draft: S) => void,
+): Partial<S> | null;
+```
+
+Returns a `Partial<S>` containing only the top-level keys that changed, or `null` if nothing was modified.
+
+---
+
+## Examples
+
+### Flat mutation
+
+```typescript
+const state = { name: 'Alice', age: 30 };
+const changes = produceDraft(state, draft => {
+  draft.name = 'Bob';
+});
+// changes: { name: 'Bob' }
+```
+
+### Nested mutation
+
+Nested plain objects are proxied recursively. Mutating a nested property triggers a shallow copy of each object on the path, preserving structural sharing for unchanged subtrees.
+
+```typescript
+const state = {
+  user: { name: 'Alice', address: { city: 'NYC' } },
+  settings: { theme: 'dark' },
+};
+
+const changes = produceDraft(state, draft => {
+  draft.user.address.city = 'LA';
+});
+// changes: { user: { name: 'Alice', address: { city: 'LA' } } }
+// state.settings === changes is not present — unchanged subtree untouched
+```
+
+### Structural sharing
+
+Unchanged subtrees keep their original references:
+
+```typescript
+const state = { a: { x: 1 }, b: { y: 2 } };
+const changes = produceDraft(state, draft => {
+  draft.a.x = 99;
+});
+// changes.a is a new object ({ x: 99 })
+// state.b was never copied — it's not in the partial at all
+```
+
+### No-op detection
+
+Assigning the same value by reference produces no changes:
+
+```typescript
+const state = { name: 'Alice', age: 30 };
+const changes = produceDraft(state, draft => {
+  draft.name = 'Alice'; // same value
+});
+// changes: null
+```
+
+---
+
+## Limitations
+
+- **Arrays** are not proxied. Mutating an array in place (`push`, `splice`, index assignment) is not detected. Replace the entire array via assignment instead:
+
+  ```typescript
+  // Bad: push is not detected
+  draft.items.push(newItem);
+
+  // Good: replace the array
+  draft.items = [...draft.items, newItem];
+  ```
+
+- **Class instances, Dates, Maps, Sets** are not proxied. Only plain objects (`Object.prototype` or `null` prototype) receive copy-on-write proxies. Non-POJO values pass through as-is and must be replaced via assignment.