mvc-kit 2.12.0 → 2.12.2

package/src/EventBus.ts

@@ -0,0 +1,110 @@
+import type { Disposable } from './types';
+import { bindPublicMethods } from './bindPublicMethods';
+
+const PROTECTED_KEYS = new Set(['addCleanup']);
+type Handler<T> = (payload: T) => void;
+
+/**
+ * Typed pub/sub event bus.
+ */
+export class EventBus<E extends Record<string, any>> implements Disposable {
+  /** Phantom type brand — enables correct inference of E in generic helpers like useEvent(). */
+  declare readonly _types: E;
+
+  private _disposed = false;
+  private _handlers = new Map<keyof E, Set<Handler<unknown>>>();
+  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;
+  }
+
+  /** AbortSignal that fires when this instance is disposed. Lazily created. */
+  get disposeSignal(): AbortSignal {
+    if (!this._abortController) {
+      this._abortController = new AbortController();
+    }
+    return this._abortController.signal;
+  }
+
+  /**
+   * Emit an event with a payload.
+   */
+  emit<K extends keyof E>(event: K, payload: E[K]): void {
+    if (this._disposed) {
+      throw new Error('Cannot emit on disposed EventBus');
+    }
+
+    const handlers = this._handlers.get(event);
+    if (handlers) {
+      for (const handler of handlers) {
+        handler(payload);
+      }
+    }
+  }
+
+  /**
+   * Subscribe to an event. Returns unsubscribe function.
+   */
+  on<K extends keyof E>(event: K, handler: Handler<E[K]>): () => void {
+    if (this._disposed) {
+      return () => {};
+    }
+
+    let handlers = this._handlers.get(event);
+    if (!handlers) {
+      handlers = new Set();
+      this._handlers.set(event, handlers);
+    }
+
+    handlers.add(handler as Handler<unknown>);
+
+    return () => {
+      handlers!.delete(handler as Handler<unknown>);
+    };
+  }
+
+  /**
+   * Subscribe to an event once. Auto-unsubscribes after first invocation.
+   */
+  once<K extends keyof E>(event: K, handler: Handler<E[K]>): () => void {
+    const unsubscribe = this.on(event, (payload) => {
+      unsubscribe();
+      handler(payload);
+    });
+    return unsubscribe;
+  }
+
+  /** 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?.();
+    this._handlers.clear();
+  }
+
+  /** 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 during dispose(). Override for custom teardown. @protected */
+  protected onDispose?(): void;
+}

package/src/Feed.md

@@ -0,0 +1,218 @@
+# Feed
+
+Cursor-based feed state manager for server-side pagination (infinite scroll / load-more patterns). Optionally accumulates items across pages. Extends [`Trackable`](./Trackable.md) — subscribable, disposable, and auto-bound.
+
+---
+
+## When to Use
+
+Use Feed as a ViewModel property to track cursor position, whether more pages are available, and optionally accumulate items across pages. Pair with `Resource.upsert()` for shared data caches, or use Feed's built-in `appendPage()`/`prependPage()` for component-scoped item lists.
+
+For client-side page-based pagination, use `Pagination` instead.
+
+---
+
+## Creating a Feed Instance
+
+```typescript
+import { Feed } from 'mvc-kit';
+
+// Untyped (cursor/hasMore only)
+readonly feed = new Feed();
+
+// Typed (with item accumulation)
+readonly feed = new Feed<Message>();
+```
+
+Initial state: `cursor = null`, `hasMore = true`, `items = []`.
+
+---
+
+## API
+
+### Readable State
+
+#### `cursor: string | null`
+
+Current pagination cursor. `null` before the first page is loaded.
+
+#### `hasMore: boolean`
+
+Whether the server reported more pages available. Starts as `true`.
+
+#### `items: readonly T[]`
+
+Accumulated items (from `appendPage`/`prependPage`). Returns a frozen array with a new reference on each change (safe for React rendering). Empty by default.
+
+#### `count: number`
+
+Number of accumulated items.
+
+### Actions
+
+#### `setResult(result: { hasMore: boolean; cursor?: string | null }): void`
+
+Update cursor/hasMore only (does **not** affect items). Use when item storage is managed externally (e.g., via Resource):
+
+```typescript
+const result = await fetchPosts(this.feed.cursor, 20, this.disposeSignal);
+this.resource.upsert(...result.items);
+this.feed.setResult(result);
+```
+
+#### `appendPage(page: FeedPage<T>): void`
+
+Append page items and update cursor/hasMore. Use for "load more" / infinite scroll:
+
+```typescript
+const page = await this.service.getMessages(id, this.disposeSignal);
+this.feed.appendPage(page); // items accessible via this.feed.items
+```
+
+#### `prependPage(page: FeedPage<T>): void`
+
+Prepend page items and update cursor/hasMore. Use for "load newer" patterns (e.g., real-time feeds).
+
+#### `push(...items: T[]): void`
+
+Add items without affecting cursor/hasMore. Use for local insertions (e.g., optimistic sends):
+
+```typescript
+this.feed.push(newMessage);
+```
+
+#### `filter(predicate: (item: T) => boolean): void`
+
+Remove items that don't match the predicate. No-op (no notification) if nothing is filtered out. Does not affect cursor/hasMore:
+
+```typescript
+this.feed.filter(msg => msg.id !== deletedId);
+```
+
+#### `replacePage(page: FeedPage<T>): void`
+
+Replace all items and update cursor/hasMore atomically (single notification). Ideal for pull-to-refresh:
+
+```typescript
+async refresh() {
+  const page = await this.service.getLatest(this.disposeSignal);
+  this.feed.replacePage(page); // clears old items, sets new ones in one go
+}
+```
+
+#### `reset(): void`
+
+Reset to initial state (`cursor = null`, `hasMore = true`, `items = []`). Use when filters change and you need to reload from the beginning.
+
+### Subscribable Interface
+
+#### `subscribe(cb: () => void): () => void`
+
+Subscribe to state changes. Returns an unsubscribe function.
+
+---
+
+## FeedPage Type
+
+A convenience type for server response shapes:
+
+```typescript
+interface FeedPage<T> {
+  items: T[];
+  hasMore: boolean;
+  cursor?: string | null;
+}
+```
+
+---
+
+## ViewModel Integration
+
+### With Resource (shared data cache)
+
+```typescript
+class SocialFeedVM extends ViewModel {
+  private resource = singleton(PostsResource);
+  readonly feed = new Feed();
+
+  get items() { return this.resource.items; }
+  get hasMore() { return this.feed.hasMore; }
+
+  protected onInit() {
+    if (this.resource.length === 0) this.loadMore();
+  }
+
+  async loadMore() {
+    const result = await fetchPosts(this.feed.cursor, 20, this.disposeSignal);
+    this.resource.upsert(...result.items);
+    this.feed.setResult(result);
+  }
+}
+```
+
+### With Item Accumulation (component-scoped data)
+
+```typescript
+class MessageThreadVM extends ViewModel<{ draft: string }> {
+  readonly feed = new Feed<Message>();
+
+  get messages() { return this.feed.items; }
+
+  async loadConversation(id: string) {
+    this.feed.reset();
+    const page = await this.service.getMessages(id, this.disposeSignal);
+    this.feed.appendPage(page);
+  }
+
+  async loadOlder() {
+    if (!this.feed.hasMore) return;
+    const page = await this.service.getMessages(id, this.disposeSignal, { cursor: this.feed.cursor });
+    this.feed.appendPage(page);
+  }
+}
+```
+
+---
+
+## React Usage with InfiniteScroll
+
+```tsx
+function SocialFeed() {
+  const [, vm] = useLocal(SocialFeedVM, {});
+  return (
+    <InfiniteScroll
+      hasMore={vm.hasMore}
+      loading={vm.async.loadMore?.loading}
+      onLoadMore={() => vm.loadMore()}
+      renderEnd={() => <p>You've seen it all!</p>}
+    >
+      <CardList
+        items={vm.items}
+        renderItem={post => <PostCard post={post} />}
+      />
+    </InfiniteScroll>
+  );
+}
+```
+
+### Chat-style (reverse scroll)
+
+```tsx
+<InfiniteScroll
+  hasMore={vm.feed.hasMore}
+  loading={vm.async.loadOlder.loading}
+  onLoadMore={() => vm.loadOlder()}
+  direction="up"
+>
+  {vm.messages.map(msg => <MessageBubble key={msg.id} message={msg} />)}
+</InfiniteScroll>
+```
+
+## 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 { reset, appendPage } = feed;
+<button onClick={reset}>Refresh</button> // point-free works
+```