@caperjs/core 0.1.0

package/src/store/Store.test.ts

@@ -0,0 +1,146 @@
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+import type { IApplication } from '../core';
+import { Store } from './Store';
+
+type FakePlugin = {
+  id: string;
+  save?: (key: string, data: any) => Promise<any>;
+  load?: (key: string) => Promise<any>;
+};
+
+function makeApp(plugins: FakePlugin[]): IApplication {
+  const map = new Map<string, FakePlugin>();
+  for (const p of plugins) map.set(p.id, p);
+  return {
+    _plugins: map,
+    getPlugin: (id: string) => map.get(id),
+  } as unknown as IApplication;
+}
+
+describe('Store', () => {
+  let errorSpy: ReturnType<typeof vi.spyOn>;
+
+  beforeEach(() => {
+    errorSpy = vi.spyOn(console, 'error').mockImplementation(() => {});
+  });
+  afterEach(() => {
+    errorSpy.mockRestore();
+  });
+
+  it('getAdapter throws for missing plugin', () => {
+    const store = new Store().initialize(makeApp([]));
+    expect(() => store.getAdapter('missing' as never)).toThrow(/not found/);
+  });
+
+  it('getAdapter throws when plugin is not storage-capable', () => {
+    const store = new Store().initialize(makeApp([{ id: 'p1' }]));
+    expect(() => store.getAdapter('p1' as never)).toThrow(/not storage-capable/);
+  });
+
+  it('hasAdapter reflects storage capability', () => {
+    const store = new Store().initialize(
+      makeApp([
+        { id: 'capable', save: async () => {}, load: async () => {} },
+        { id: 'not' },
+      ]),
+    );
+    expect(store.hasAdapter('capable' as never)).toBe(true);
+    expect(store.hasAdapter('not' as never)).toBe(false);
+    expect(store.hasAdapter('missing' as never)).toBe(false);
+  });
+
+  it('save (awaited) routes to adapter.save and returns its value', async () => {
+    const save = vi.fn(async (k: string, d: any) => ({ k, d }));
+    const store = new Store().initialize(
+      makeApp([{ id: 'a', save, load: async () => undefined }]),
+    );
+    const result = await store.save('a' as never, 'key', 42);
+    expect(save).toHaveBeenCalledWith('key', 42);
+    expect(result).toEqual([{ k: 'key', d: 42 }]);
+  });
+
+  it('save fire-and-forget emits onError when adapter.save rejects', async () => {
+    const err = new Error('boom');
+    const store = new Store().initialize(
+      makeApp([
+        {
+          id: 'a',
+          save: async () => {
+            throw err;
+          },
+          load: async () => undefined,
+        },
+      ]),
+    );
+    const errHandler = vi.fn();
+    store.onError.connect(errHandler);
+
+    const result = await store.save('a' as never, 'k', 1, false);
+    // Wait for the fire-and-forget promise inside `result[0]` to settle.
+    await result[0];
+
+    expect(errHandler).toHaveBeenCalledTimes(1);
+    const detail = errHandler.mock.calls[0][0];
+    expect(detail.adapterId).toBe('a');
+    expect(detail.operation).toBe('save');
+    expect(detail.key).toBe('k');
+    expect(detail.error).toBe(err);
+  });
+
+  it('save (awaited) emits onError and rethrows on adapter failure', async () => {
+    const err = new Error('nope');
+    const store = new Store().initialize(
+      makeApp([
+        {
+          id: 'a',
+          save: async () => {
+            throw err;
+          },
+          load: async () => undefined,
+        },
+      ]),
+    );
+    const errHandler = vi.fn();
+    store.onError.connect(errHandler);
+
+    await expect(store.save('a' as never, 'k', 1, true)).rejects.toBe(err);
+    expect(errHandler).toHaveBeenCalledTimes(1);
+    expect(errHandler.mock.calls[0][0].operation).toBe('save');
+  });
+
+  it('load emits onError and rethrows on adapter failure', async () => {
+    const err = new Error('read fail');
+    const store = new Store().initialize(
+      makeApp([
+        {
+          id: 'a',
+          save: async () => undefined,
+          load: async () => {
+            throw err;
+          },
+        },
+      ]),
+    );
+    const errHandler = vi.fn();
+    store.onError.connect(errHandler);
+
+    await expect(store.load('a' as never, 'k')).rejects.toBe(err);
+    expect(errHandler).toHaveBeenCalledTimes(1);
+    expect(errHandler.mock.calls[0][0].operation).toBe('load');
+  });
+
+  it('save with "*" fans out to every storage-capable plugin', async () => {
+    const saveA = vi.fn(async () => 'a');
+    const saveB = vi.fn(async () => 'b');
+    const store = new Store().initialize(
+      makeApp([
+        { id: 'a', save: saveA, load: async () => undefined },
+        { id: 'b', save: saveB, load: async () => undefined },
+        { id: 'c' }, // not storage-capable → must be skipped
+      ]),
+    );
+    await store.save('*' as never, 'k', 1);
+    expect(saveA).toHaveBeenCalledWith('k', 1);
+    expect(saveB).toHaveBeenCalledWith('k', 1);
+  });
+});

package/src/store/Store.ts

@@ -0,0 +1,192 @@
+import type { IApplication } from '../core';
+import { isStorageCapable, type IStorageCapability } from '../core/interfaces/IStorageCapability';
+import type { IPlugin } from '../plugins/Plugin';
+import { Signal } from '../signals';
+import { type AppTypeOverrides, Logger } from '../utils';
+
+export type StoreErrorDetail = {
+  adapterId: string;
+  operation: 'save' | 'load';
+  key: string;
+  error: Error;
+};
+
+type AppPlugins = AppTypeOverrides['Plugins'];
+
+/**
+ * Configuration for a single save call.
+ */
+type AdapterSaveConfig = {
+  adapterId: string;
+  awaitSave: boolean;
+};
+
+/**
+ * Thin façade over the Application's plugin registry.
+ *
+ * A "storage adapter" is nothing more than a `Plugin` whose instance implements
+ * {@link IStorageCapability}. The `Store` doesn't own a second registry — it
+ * just filters `app._plugins` for storage-capable entries and routes save/load
+ * calls through them.
+ */
+export interface IStore {
+  initialize(app: IApplication): IStore;
+
+  destroy(): void;
+
+  getAdapter<T extends IStorageCapability = IStorageCapability>(adapterId: AppPlugins): T;
+
+  hasAdapter(adapterId: AppPlugins): boolean;
+
+  save(
+    adapterId: AppPlugins | AppPlugins[] | Partial<AdapterSaveConfig> | Partial<AdapterSaveConfig>[],
+    key: string,
+    data: any,
+    awaitSave?: boolean,
+  ): Promise<any>;
+
+  load(adapterId: AppPlugins, key: string): Promise<any>;
+
+  onError: Signal<(detail: StoreErrorDetail) => void>;
+}
+
+export class Store implements IStore {
+  public readonly onError = new Signal<(detail: StoreErrorDetail) => void>();
+  private _app!: IApplication;
+
+  public initialize(app: IApplication): IStore {
+    this._app = app;
+    return this;
+  }
+
+  public destroy(): void {
+    // Plugin lifecycle is owned by Application. Nothing to clean up here.
+    this.onError.disconnectAll();
+  }
+
+  private _emitError(detail: StoreErrorDetail): void {
+    Logger.error(
+      `[Store.${detail.operation}] adapter='${detail.adapterId}' key='${detail.key}': ${detail.error.message}`,
+    );
+    this.onError.emit(detail);
+  }
+
+  /**
+   * Returns a storage-capable plugin by id. Throws if the plugin is missing or
+   * does not implement {@link IStorageCapability}.
+   */
+  public getAdapter<T extends IStorageCapability = IStorageCapability>(adapterId: AppPlugins): T {
+    const plugin = this._app.getPlugin(adapterId as string) as unknown as IPlugin & Partial<IStorageCapability>;
+    if (!plugin) {
+      throw new Error(`Adapter ${String(adapterId)} not found`);
+    }
+    if (!isStorageCapable(plugin)) {
+      throw new Error(`Plugin '${String(adapterId)}' is not storage-capable (missing save/load)`);
+    }
+    return plugin as unknown as T;
+  }
+
+  public hasAdapter(adapterId: AppPlugins): boolean {
+    const plugin = this._app.getPlugin(adapterId as string) as unknown as IPlugin | undefined;
+    return !!plugin && isStorageCapable(plugin);
+  }
+
+  /**
+   * Iterates every storage-capable plugin currently registered with the app.
+   */
+  private allAdapterIds(): string[] {
+    // Application exposes its plugin map as `_plugins` (protected). We reach in
+    // via a known cast rather than widening the public IApplication surface.
+    const map = (this._app as unknown as { _plugins: Map<string, IPlugin> })._plugins;
+    const ids: string[] = [];
+    if (map) {
+      for (const [id, plugin] of map) {
+        if (isStorageCapable(plugin)) ids.push(id);
+      }
+    }
+    return ids;
+  }
+
+  public async save(
+    adapterId: AppPlugins | AppPlugins[] | Partial<AdapterSaveConfig> | Partial<AdapterSaveConfig>[],
+    key: string,
+    data: any,
+    awaitSave = true,
+  ): Promise<any> {
+    let keys: string[] | Partial<AdapterSaveConfig>[] = [];
+    const result: any[] = [];
+
+    if (!Array.isArray(adapterId)) {
+      if (typeof adapterId === 'object') {
+        keys = [adapterId];
+      } else {
+        keys = [adapterId as string];
+      }
+    } else {
+      keys = adapterId as string[] | Partial<AdapterSaveConfig>[];
+    }
+
+    if ((keys[0] as string) === '*' || (keys[0] as Partial<AdapterSaveConfig>)?.adapterId === '*') {
+      keys = this.allAdapterIds();
+    }
+
+    for (let i = 0; i < keys.length; i++) {
+      let aKey: string;
+      let shouldAwait = false;
+      if (typeof keys[i] === 'object') {
+        const obj = keys[i] as Partial<AdapterSaveConfig>;
+        aKey = obj.adapterId as string;
+        shouldAwait = obj.awaitSave ?? false;
+      } else {
+        aKey = keys[i] as unknown as string;
+        shouldAwait = awaitSave;
+      }
+
+      let adapter: IStorageCapability;
+      try {
+        adapter = this.getAdapter(aKey as AppPlugins);
+      } catch (e) {
+        this._emitError({ adapterId: aKey, operation: 'save', key, error: e as Error });
+        throw e;
+      }
+
+      if (shouldAwait) {
+        try {
+          result.push(await adapter.save(key, data));
+        } catch (e) {
+          this._emitError({ adapterId: aKey, operation: 'save', key, error: e as Error });
+          throw e;
+        }
+      } else {
+        // Fire-and-forget: don't block caller, but never let failures vanish
+        // as unhandled promise rejections. Route them through onError instead.
+        const idForSignal = aKey;
+        result.push(
+          adapter.save(key, data).catch((e: unknown) => {
+            this._emitError({
+              adapterId: idForSignal,
+              operation: 'save',
+              key,
+              error: e as Error,
+            });
+          }),
+        );
+      }
+    }
+    return result;
+  }
+
+  public async load(adapterId: AppPlugins, key: string): Promise<any> {
+    try {
+      return await this.getAdapter(adapterId).load(key);
+    } catch (e) {
+      this._emitError({
+        adapterId: adapterId as string,
+        operation: 'load',
+        key,
+        error: e as Error,
+      });
+      throw e;
+    }
+  }
+}

package/src/store/index.ts

@@ -0,0 +1 @@
+export * from './Store';

package/src/types/framework.d.ts

@@ -0,0 +1,47 @@
+import type { Application } from '../core/Application';
+import type { Action, ActionContext } from '../plugins';
+import type { DataSchema } from '../plugins/DataAdapter';
+
+declare module '../utils/types' {
+  export interface AppTypeOverrides {
+    App: Application;
+    Data: DataSchema;
+    Contexts: ActionContext;
+    Actions: Action;
+    ActionMap: Record<string, Action>;
+    Scenes: string;
+    Plugins: string;
+  }
+  export interface AssetTypeOverrides {
+    Texture: string;
+    TPSFrames: string;
+    SpriteSheet: string;
+    SpineData: string;
+    Audio: string;
+    FontFamily: string;
+    BitmapFontFamily: string;
+    Bundles: string;
+  }
+}
+
+declare module '@caperjs/core' {
+  export interface AppTypeOverrides {
+    App: Application;
+    Data: DataSchema;
+    Contexts: ActionContext;
+    Actions: Action;
+    ActionMap: Record<string, Action>;
+    Scenes: string;
+    Plugins: string;
+  }
+  export interface AssetTypeOverrides {
+    Texture: string;
+    TPSFrames: string;
+    SpriteSheet: string;
+    SpineData: string;
+    Audio: string;
+    FontFamily: string;
+    BitmapFontFamily: string;
+    Bundles: string;
+  }
+}

package/src/types/gsap.d.ts

@@ -0,0 +1,26 @@
+ 
+
+import { AppTypeOverrides } from '../utils';
+
+/**
+ * An interface for custom GSAP eases.
+ * This interface can be augmented in your application to provide strong typing for your custom eases.
+ *
+ * @example
+ * ```ts
+ * // src/types/custom-eases.d.ts
+ * declare module '@caperjs/core/types/gsap' {
+ *   interface CustomEase {
+ *     'my-custom-ease': any;
+ *     'another-ease': any;
+ *   }
+ * }
+ * ```
+ */
+
+declare module 'gsap/gsap-core' {
+  // We can't directly augment the EaseString type alias, so we'll augment TweenVars instead.
+  interface TweenVars {
+    ease?: EaseString | AppTypeOverrides['CustomEases'];
+  }
+}