✅ Add tests for application

Author: jpolo

packages/application/src/ConfigurationRef.ts

@@ -6,7 +6,24 @@ export interface ConfigurationRef<Configuration> extends Ref<Configuration> {
    */
   readonly initial: Configuration;
 
+  /**
+   * Get a specific configuration value by key
+   *
+   * @param key the configuration key
+   */
   get<Key extends keyof Configuration>(key: Key): Configuration[Key];
+
+  /**
+   * Update the configuration by merging the current configuration with the given patch
+   *
+   * @param patch the partial configuration to merge with the current configuration
+   */
   update(patch: Partial<Configuration>): void;
-  modify(fn: (current: Configuration) => Configuration): void;
+
+  /**
+   * Modify the configuration using a mapping function
+   *
+   * @param mapFn a function that takes the current configuration and returns a new configuration
+   */
+  modify(mapFn: (current: Configuration) => Configuration): void;
 }

packages/application/src/Meta.ts

@@ -0,0 +1,3 @@
+export interface Meta {
+  readonly name: string;
+}

packages/application/src/index.ts

@@ -1,5 +1,7 @@
 export * from './ConfigurationRef.js';
+export * from './Meta.js';
 export * from './State.js';
+export * from './StateKey.js';
 export * from './useConfiguration.js';
 export * from './useState.js';
 export * from './useRef.js';

packages/application/src/useConfiguration.spec.ts

@@ -0,0 +1,58 @@
+import { describe, expect, it } from 'vitest';
+import { Ref } from '@w5s/core';
+import { useConfiguration } from './useConfiguration.js';
+
+describe(useConfiguration, () => {
+  it('should initialize configuration and expose initial', () => {
+    const store = Ref({});
+    const meta = { name: 'app' } as const;
+    const initial = { mode: 'light', retries: 2 };
+
+    const configuration = useConfiguration(meta, initial, store);
+
+    expect(configuration.current).toEqual(initial);
+    expect(configuration.initial).toEqual(initial);
+    expect(store.current).toEqual({
+      app: {
+        configuration: initial,
+      },
+    });
+  });
+
+  it('should support get, update, and modify', () => {
+    const store = Ref({});
+    const meta = { name: 'app' } as const;
+    const initial = { mode: 'light', retries: 2 };
+
+    const configuration = useConfiguration(meta, initial, store);
+
+    expect(configuration.get('mode')).toBe('light');
+
+    const previous = configuration.current;
+    configuration.update({ retries: 3 });
+    expect(configuration.current).toEqual({ mode: 'light', retries: 3 });
+    expect(configuration.current).not.toBe(previous);
+
+    configuration.modify((current) => ({ ...current, mode: 'dark' }));
+    expect(configuration.current).toEqual({ mode: 'dark', retries: 3 });
+  });
+
+  it('should not override existing configuration in store', () => {
+    const store = Ref({
+      app: {
+        configuration: { mode: 'dark', retries: 5 },
+        other: true,
+      },
+    });
+    const meta = { name: 'app' } as const;
+    const initial = { mode: 'light', retries: 1 };
+
+    const configuration = useConfiguration(meta, initial, store);
+
+    expect(configuration.current).toEqual({ mode: 'dark', retries: 5 });
+    expect(store.current.app).toEqual({
+      configuration: { mode: 'dark', retries: 5 },
+      other: true,
+    });
+  });
+});

packages/application/src/useConfiguration.ts

@@ -3,13 +3,14 @@ import { useRef } from './useRef.js';
 import { useNamespace } from './useNamespace.js';
 import type { Ref } from '@w5s/core';
 import type { State } from './State.js';
+import type { Meta } from './Meta.js';
 
 export function useConfiguration<Configuration>(
-  name: string | { name: string },
+  meta: Meta,
   initial: Configuration,
   store?: Ref<State>,
 ): ConfigurationRef<Configuration> {
-  const namespace = useNamespace(name, store);
+  const namespace = useNamespace(meta, store);
   const configuration = useRef(namespace, 'configuration', initial);
 
   function modify(fn: (current: Configuration) => Configuration): void {

packages/application/src/useNamespace.spec.ts

@@ -0,0 +1,39 @@
+import { describe, expect, it } from 'vitest';
+import { Ref } from '@w5s/core';
+import { useNamespace } from './useNamespace.js';
+
+describe(useNamespace, () => {
+  it('should create namespace in store when missing', () => {
+    const store = Ref({});
+    const meta = { name: 'app' } as const;
+
+    const namespace = useNamespace(meta, store);
+
+    expect(namespace.current).toEqual({});
+    expect(store.current).toEqual({ app: {} });
+  });
+
+  it('should return existing namespace from store', () => {
+    const existing = { configuration: { mode: 'dark' }, state: { counter: 2 } };
+    const store = Ref({ app: existing });
+    const meta = { name: 'app' } as const;
+
+    const namespace = useNamespace(meta, store);
+
+    expect(namespace.current).toEqual(existing);
+    expect(namespace.current).toBe(existing);
+  });
+
+  it('should keep other namespaces intact when updating current namespace', () => {
+    const store = Ref({ other: { state: { value: 1 } } });
+    const meta = { name: 'app' } as const;
+
+    const namespace = useNamespace(meta, store);
+    namespace.current = { configuration: { retries: 2 } };
+
+    expect(store.current).toEqual({
+      other: { state: { value: 1 } },
+      app: { configuration: { retries: 2 } },
+    });
+  });
+});

packages/application/src/useNamespace.ts

@@ -2,12 +2,28 @@ import { useRef } from './useRef.js';
 import { useStorage } from '@w5s/global-storage';
 import type { Ref } from '@w5s/core';
 import type { State } from './State.js';
+import type { Meta } from './Meta.js';
 
+/**
+ * Return a new `Ref` containing the namespace for the given `meta.name`.
+ *
+ * @example
+ * ```typescript
+ * const app = { name: 'my-app' };
+ * const namespace = useNamespace(app);
+ * namespace.current == {
+ *   ...namespace.current,
+ *   configuration: {},
+ *   state: {},
+ * };
+ * ```
+ * @param meta the meta info containing the name
+ * @param store
+ */
 export function useNamespace(
-  name: string | { name: string },
+  meta: Meta,
   store?: Ref<State>,
 ): Ref<State> {
   const initialState = Object.freeze({});
-  const key = typeof name === 'string' ? name : name.name;
-  return useRef(store == null ? useStorage(globalThis) : store, key, initialState);
+  return useRef(store == null ? useStorage(globalThis) : store, meta.name, initialState);
 }

packages/application/src/useRef.spec.ts

@@ -3,7 +3,7 @@ import { Ref } from '@w5s/core';
 import { useStorage } from '@w5s/global-storage';
 import { useRef } from './useRef.js';
 
-describe('useRef()', () => {
+describe(useRef, () => {
   describe('+ Storage', () => {
     const anyStorage = useStorage({});
 

packages/application/src/useState.spec.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from 'vitest';
+import { Ref } from '@w5s/core';
+import { useState } from './useState.js';
+
+describe(useState, () => {
+  it('should initialize state for namespace and key', () => {
+    const store = Ref({});
+    const meta = { name: 'app' } as const;
+
+    const counter = useState(meta, 'counter', 1, store);
+
+    expect(counter.current).toBe(1);
+    expect(store.current).toEqual({
+      app: {
+        state: {
+          counter: 1,
+        },
+      },
+    });
+  });
+
+  it('should not override existing state value', () => {
+    const store = Ref({
+      app: {
+        state: {
+          counter: 5,
+        },
+      },
+    });
+    const meta = { name: 'app' } as const;
+
+    const counter = useState(meta, 'counter', 1, store);
+
+    expect(counter.current).toBe(5);
+    expect(store.current.app.state).toEqual({ counter: 5 });
+  });
+
+  it('should preserve other namespace data when adding state', () => {
+    const store = Ref({
+      app: {
+        configuration: { mode: 'dark' },
+      },
+    });
+    const meta = { name: 'app' } as const;
+
+    const counter = useState(meta, 'counter', 1, store);
+
+    expect(counter.current).toBe(1);
+    expect(store.current).toEqual({
+      app: {
+        configuration: { mode: 'dark' },
+        state: { counter: 1 },
+      },
+    });
+  });
+});

packages/application/src/useState.ts

@@ -3,9 +3,24 @@ import { useNamespace } from './useNamespace.js';
 import { useRef } from './useRef.js';
 import type { State } from './State.js';
 import type { StateKey } from './StateKey.js';
+import type { Meta } from './Meta.js';
 
-export function useState<T>(name: string | { name: string }, key: StateKey, initial: T, store?: Ref<State>): Ref<T> {
-  const namespace = useNamespace(name, store);
+/**
+ * Return a new `Ref` containing the state for the given `meta.name` and `key`.
+ *
+ * @example
+ * ```typescript
+ * const app = { name: 'my-app' };
+ * const counterRef = useState(app, 'counter', 1);
+ * counterRef.current += 1;
+ * ```
+ * @param meta the meta info containing the name
+ * @param key the key of the state
+ * @param initial the initial value of the state
+ * @param store the store containing the state, default to global storage
+ */
+export function useState<T>(meta: Meta, key: StateKey, initial: T, store?: Ref<State>): Ref<T> {
+  const namespace = useNamespace(meta, store);
   const state = useRef(namespace, 'state', Object.freeze({}));
   return useRef(state, key, initial);
 }