mvc-kit 2.12.0 → 2.12.2

package/src/Service.test.ts

@@ -0,0 +1,241 @@
+import { describe, it, expect, beforeEach } from 'vitest';
+import { Service } from './Service';
+import { singleton, teardown, teardownAll } from './singleton';
+
+class ApiService extends Service {
+  onDisposeCalled = false;
+
+  protected onDispose(): void {
+    this.onDisposeCalled = true;
+  }
+
+  async fetchData(): Promise<string> {
+    return 'data';
+  }
+}
+
+class StorageService extends Service {
+  private data: Map<string, string> = new Map();
+
+  set(key: string, value: string): void {
+    this.data.set(key, value);
+  }
+
+  get(key: string): string | undefined {
+    return this.data.get(key);
+  }
+
+  protected onDispose(): void {
+    this.data.clear();
+  }
+}
+
+describe('Service', () => {
+  describe('initialization', () => {
+    it('starts not disposed', () => {
+      const service = new ApiService();
+      expect(service.disposed).toBe(false);
+    });
+  });
+
+  describe('dispose', () => {
+    it('sets disposed to true', () => {
+      const service = new ApiService();
+      service.dispose();
+      expect(service.disposed).toBe(true);
+    });
+
+    it('calls onDispose hook', () => {
+      const service = new ApiService();
+      expect(service.onDisposeCalled).toBe(false);
+      service.dispose();
+      expect(service.onDisposeCalled).toBe(true);
+    });
+
+    it('is idempotent', () => {
+      let callCount = 0;
+      class CountingService extends Service {
+        protected onDispose(): void {
+          callCount++;
+        }
+      }
+      const service = new CountingService();
+      service.dispose();
+      service.dispose();
+      service.dispose();
+      expect(callCount).toBe(1);
+    });
+  });
+
+  describe('init', () => {
+    it('starts not initialized', () => {
+      const service = new ApiService();
+      expect(service.initialized).toBe(false);
+    });
+
+    it('sets initialized to true after init()', () => {
+      const service = new ApiService();
+      service.init();
+      expect(service.initialized).toBe(true);
+    });
+
+    it('calls onInit hook', () => {
+      let called = false;
+      class InitService extends Service {
+        protected onInit() {
+          called = true;
+        }
+      }
+      const service = new InitService();
+      service.init();
+      expect(called).toBe(true);
+    });
+
+    it('is idempotent — onInit called only once', () => {
+      let callCount = 0;
+      class CountingService extends Service {
+        protected onInit() {
+          callCount++;
+        }
+      }
+      const service = new CountingService();
+      service.init();
+      service.init();
+      service.init();
+      expect(callCount).toBe(1);
+    });
+
+    it('supports async onInit', async () => {
+      let resolved = false;
+      class AsyncService extends Service {
+        protected async onInit() {
+          await Promise.resolve();
+          resolved = true;
+        }
+      }
+      const service = new AsyncService();
+      await service.init();
+      expect(resolved).toBe(true);
+    });
+
+    it('is a no-op after dispose', () => {
+      let called = false;
+      class InitService extends Service {
+        protected onInit() {
+          called = true;
+        }
+      }
+      const service = new InitService();
+      service.dispose();
+      service.init();
+      expect(called).toBe(false);
+      expect(service.initialized).toBe(false);
+    });
+  });
+
+  describe('methods', () => {
+    it('can perform operations', async () => {
+      const service = new ApiService();
+      const result = await service.fetchData();
+      expect(result).toBe('data');
+    });
+
+    it('can manage state', () => {
+      const service = new StorageService();
+      service.set('key', 'value');
+      expect(service.get('key')).toBe('value');
+    });
+  });
+
+  describe('singleton integration', () => {
+    beforeEach(() => {
+      teardownAll();
+    });
+
+    it('can be used with singleton registry', () => {
+      const s1 = singleton(ApiService);
+      const s2 = singleton(ApiService);
+      expect(s1).toBe(s2);
+    });
+
+    it('maintains separate singletons per class', () => {
+      const api = singleton(ApiService);
+      const storage = singleton(StorageService);
+      expect(api).not.toBe(storage);
+    });
+
+    it('can be torn down', () => {
+      const service = singleton(ApiService);
+      teardown(ApiService);
+      expect(service.disposed).toBe(true);
+    });
+  });
+
+  describe('signal and addCleanup', () => {
+    it('signal returns an AbortSignal', () => {
+      const service = new ApiService();
+      expect(service.disposeSignal).toBeInstanceOf(AbortSignal);
+    });
+
+    it('returns the same signal on multiple accesses', () => {
+      const service = new ApiService();
+      const s1 = service.disposeSignal;
+      const s2 = service.disposeSignal;
+      expect(s1).toBe(s2);
+    });
+
+    it('signal is not aborted before dispose', () => {
+      const service = new ApiService();
+      expect(service.disposeSignal.aborted).toBe(false);
+    });
+
+    it('signal is aborted after dispose', () => {
+      const service = new ApiService();
+      const signal = service.disposeSignal;
+      service.dispose();
+      expect(signal.aborted).toBe(true);
+    });
+
+    it('signal is aborted before onDispose runs', () => {
+      let wasAbortedDuringDispose = false;
+      class CheckService extends Service {
+        protected onDispose(): void {
+          wasAbortedDuringDispose = this.disposeSignal.aborted;
+        }
+      }
+      const service = new CheckService();
+      service.disposeSignal; // force lazy creation
+      service.dispose();
+      expect(wasAbortedDuringDispose).toBe(true);
+    });
+
+    it('addCleanup fires on dispose', () => {
+      let cleaned = false;
+      class CleanupService extends Service {
+        setup() {
+          this.addCleanup(() => { cleaned = true; });
+        }
+      }
+      const service = new CleanupService();
+      service.setup();
+      expect(cleaned).toBe(false);
+      service.dispose();
+      expect(cleaned).toBe(true);
+    });
+
+    it('dispose works without accessing signal (lazy, zero cost)', () => {
+      const service = new ApiService();
+      service.dispose();
+      expect(service.disposed).toBe(true);
+    });
+  });
+
+  describe('method binding', () => {
+    it('subclass methods work point-free', () => {
+      const svc = new StorageService();
+      const { set, get } = svc;
+      set('key', 'value');
+      expect(get('key')).toBe('value');
+    });
+  });
+});

package/src/Service.ts

@@ -0,0 +1,72 @@
+import type { Disposable } from './types';
+import { bindPublicMethods } from './bindPublicMethods';
+
+const PROTECTED_KEYS = new Set(['addCleanup']);
+
+/**
+ * Base class for non-reactive infrastructure services.
+ * Services encapsulate external dependencies like APIs, storage, etc.
+ */
+export abstract class Service implements Disposable {
+  private _disposed = false;
+  private _initialized = false;
+  private _abortController: AbortController | null = null;
+  private _cleanups: (() => void)[] | null = null;
+
+  constructor() {
+    bindPublicMethods(this, Object.prototype, PROTECTED_KEYS);
+  }
+
+  /** Whether this instance has been disposed. */
+  get disposed(): boolean {
+    return this._disposed;
+  }
+
+  /** Whether init() has been called. */
+  get initialized(): boolean {
+    return this._initialized;
+  }
+
+  /** AbortSignal that fires when this instance is disposed. Lazily created. */
+  get disposeSignal(): AbortSignal {
+    if (!this._abortController) {
+      this._abortController = new AbortController();
+    }
+    return this._abortController.signal;
+  }
+
+  /** Initializes the instance. Called automatically by React hooks after mount. */
+  init(): void | Promise<void> {
+    if (this._initialized || this._disposed) return;
+    this._initialized = true;
+    return this.onInit?.();
+  }
+
+  /** Tears down the instance, releasing all subscriptions and resources. */
+  dispose(): void {
+    if (this._disposed) {
+      return;
+    }
+
+    this._disposed = true;
+    this._abortController?.abort();
+    if (this._cleanups) {
+      for (const fn of this._cleanups) fn();
+      this._cleanups = null;
+    }
+    this.onDispose?.();
+  }
+
+  /** Registers a cleanup function to be called on dispose. @protected */
+  protected addCleanup(fn: () => void): void {
+    if (!this._cleanups) {
+      this._cleanups = [];
+    }
+    this._cleanups.push(fn);
+  }
+
+  /** Lifecycle hook called at the end of init(). Override to load initial data. @protected */
+  protected onInit?(): void | Promise<void>;
+  /** Lifecycle hook called during dispose(). Override for custom teardown. @protected */
+  protected onDispose?(): void;
+}

package/src/Sorting.md

@@ -0,0 +1,170 @@
+# Sorting
+
+Multi-column sorting helper. Manages sort descriptors with a 3-click toggle cycle and applies sorting to arrays. Extends [`Trackable`](./Trackable.md) — subscribable, disposable, and auto-bound.
+
+---
+
+## When to Use
+
+Use Sorting as a ViewModel property to manage table/list sort state. Auto-tracking ensures ViewModel getters that read from Sorting auto-invalidate when sort state changes.
+
+---
+
+## Creating a Sorting Instance
+
+```typescript
+import { Sorting } from 'mvc-kit';
+
+// No initial sorting
+readonly sorting = new Sorting<User>();
+
+// With initial sort
+readonly sorting = new Sorting<User>({ sorts: [{ key: 'name', direction: 'asc' }] });
+```
+
+The generic parameter `<T>` is the type of items you'll sort. It's used by `apply()` and `compareFn`.
+
+---
+
+## API
+
+### Readable State
+
+#### `sorts: readonly SortDescriptor[]`
+
+Full list of active sort descriptors, in priority order.
+
+```typescript
+interface SortDescriptor {
+  key: string;
+  direction: 'asc' | 'desc';
+}
+```
+
+#### `key: string | null`
+
+Primary sort key (first descriptor), or `null` when empty.
+
+#### `direction: 'asc' | 'desc'`
+
+Primary sort direction. Defaults to `'asc'` when empty.
+
+### Query Methods
+
+#### `isSorted(key: string): boolean`
+
+Whether the given key has an active sort descriptor.
+
+#### `directionOf(key: string): 'asc' | 'desc' | null`
+
+Direction of the given key, or `null` if not sorted.
+
+#### `indexOf(key: string): number`
+
+Index of the key in the sort list, or `-1` if not sorted.
+
+### Actions
+
+#### `toggle(key: string): void`
+
+3-click cycle: **not sorted -> asc -> desc -> removed**.
+
+```typescript
+sorting.toggle('name'); // [{key:'name', dir:'asc'}]
+sorting.toggle('name'); // [{key:'name', dir:'desc'}]
+sorting.toggle('name'); // [] (removed)
+```
+
+Multi-column: toggling a new key appends it. Toggling an existing key advances its cycle without affecting others.
+
+#### `setSort(key: string, direction: 'asc' | 'desc'): void`
+
+Replace all sorts with a single sort descriptor.
+
+#### `setSorts(sorts: SortDescriptor[]): void`
+
+Replace all sorts with the given descriptors.
+
+#### `reset(): void`
+
+Clear all sort descriptors.
+
+### Pipeline
+
+#### `apply(items: T[], compareFn?): T[]`
+
+Returns a new sorted array (does not mutate the input).
+
+Default comparison: `localeCompare` for strings, `<`/`>` for others, `null` values sort first.
+
+Custom `compareFn` signature:
+
+```typescript
+(a: T, b: T, key: string, dir: 'asc' | 'desc') => number
+```
+
+### Subscribable Interface
+
+#### `subscribe(cb: () => void): () => void`
+
+Subscribe to state changes. Returns an unsubscribe function.
+
+---
+
+## ViewModel Integration
+
+Declare as a ViewModel instance property. Auto-tracking handles the rest:
+
+```typescript
+class UsersVM extends ViewModel<FilterState> {
+  readonly sorting = new Sorting<User>({ sorts: [{ key: 'name', direction: 'asc' }] });
+  private users = singleton(UsersResource);
+
+  get sorted(): User[] {
+    // Auto-invalidates when sorting changes
+    return this.sorting.apply(this.users.items);
+  }
+}
+```
+
+---
+
+## React Usage
+
+Pass the Sorting helper directly to DataTable:
+
+```tsx
+<DataTable
+  items={vm.items}
+  columns={columns}
+  sort={vm.sorting}
+/>
+```
+
+Or use the object-literal form for custom usage:
+
+```tsx
+<DataTable
+  items={vm.items}
+  columns={columns}
+  sort={vm.sorting.sorts}
+  onSort={key => vm.sorting.toggle(key)}
+/>
+```
+
+Or with plain buttons:
+
+```tsx
+<button onClick={() => vm.sorting.toggle('name')}>
+  Name {vm.sorting.directionOf('name') === 'asc' ? '↑' : vm.sorting.directionOf('name') === 'desc' ? '↓' : ''}
+</button>
+```
+
+## Method Binding
+
+All public methods are auto-bound in the constructor. You can pass them point-free as callbacks without losing `this` context:
+
+```tsx
+const { toggle } = sorting;   // destructure works
+<SortHeader onClick={toggle} /> // point-free works
+```