@ankhorage/contracts 1.6.0 → 1.7.0

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @ankhorage/contracts
 
+## 1.7.0
+
+### Minor Changes
+
+- eff4efc: Add provider-neutral state adapter contracts for path-based reads, writes, subscriptions, and optional removal support.
+
 ## 1.6.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -1,5 +1,6 @@
 export * from './auth';
 export * from './db';
+export * from './state';
 export * from './storage';
 export * from './types';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -1,5 +1,6 @@
 export * from './auth';
 export * from './db';
+export * from './state';
 export * from './storage';
 export * from './types';
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC","sourcesContent":["export * from './auth';\nexport * from './db';\nexport * from './storage';\nexport * from './types';\n"]}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,QAAQ,CAAC;AACvB,cAAc,MAAM,CAAC;AACrB,cAAc,SAAS,CAAC;AACxB,cAAc,WAAW,CAAC;AAC1B,cAAc,SAAS,CAAC","sourcesContent":["export * from './auth';\nexport * from './db';\nexport * from './state';\nexport * from './storage';\nexport * from './types';\n"]}

package/dist/state.d.ts

@@ -0,0 +1,41 @@
+export type StatePrimitive = string | number | boolean | null;
+export type StateValue = StatePrimitive | readonly StateValue[] | {
+    readonly [key: string]: StateValue;
+};
+export type StatePath = string | readonly string[];
+export interface StateAdapterCapabilities {
+    readonly subscriptions: boolean;
+    readonly computed: boolean;
+    readonly persistence: boolean;
+}
+export interface StateAdapterError {
+    readonly code: string;
+    readonly message: string;
+    readonly cause?: unknown;
+}
+export type StateSuccess<TValue = void> = [TValue] extends [void] ? {
+    readonly ok: true;
+} : {
+    readonly ok: true;
+    readonly data: TValue;
+};
+export type StateResult<TValue = void> = StateSuccess<TValue> | {
+    readonly ok: false;
+    readonly error: StateAdapterError;
+};
+export interface StateSnapshot<TValue extends StateValue = StateValue> {
+    readonly path: StatePath;
+    readonly value: TValue | undefined;
+}
+export type StateListener<TValue extends StateValue = StateValue> = (snapshot: StateSnapshot<TValue>) => void;
+export interface StateSubscription {
+    unsubscribe(): Promise<void> | void;
+}
+export interface StateAdapter {
+    readonly capabilities: StateAdapterCapabilities;
+    get<TValue extends StateValue = StateValue>(path: StatePath): StateResult<TValue | undefined>;
+    set<TValue extends StateValue = StateValue>(path: StatePath, value: TValue): StateResult;
+    subscribe<TValue extends StateValue = StateValue>(path: StatePath, listener: StateListener<TValue>): StateResult<StateSubscription>;
+    delete?(path: StatePath): StateResult;
+}
+//# sourceMappingURL=state.d.ts.map

package/dist/state.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.d.ts","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"AAAA,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,IAAI,CAAC;AAE9D,MAAM,MAAM,UAAU,GAClB,cAAc,GACd,SAAS,UAAU,EAAE,GACrB;IACE,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,UAAU,CAAC;CACpC,CAAC;AAEN,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,SAAS,MAAM,EAAE,CAAC;AAEnD,MAAM,WAAW,wBAAwB;IACvC,QAAQ,CAAC,aAAa,EAAE,OAAO,CAAC;IAChC,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;CAC/B;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED,MAAM,MAAM,YAAY,CAAC,MAAM,GAAG,IAAI,IAAI,CAAC,MAAM,CAAC,SAAS,CAAC,IAAI,CAAC,GAC7D;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;CACnB,GACD;IACE,QAAQ,CAAC,EAAE,EAAE,IAAI,CAAC;IAClB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;CACvB,CAAC;AAEN,MAAM,MAAM,WAAW,CAAC,MAAM,GAAG,IAAI,IACjC,YAAY,CAAC,MAAM,CAAC,GACpB;IACE,QAAQ,CAAC,EAAE,EAAE,KAAK,CAAC;IACnB,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;CACnC,CAAC;AAEN,MAAM,WAAW,aAAa,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU;IACnE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,SAAS,CAAC;CACpC;AAED,MAAM,MAAM,aAAa,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,IAAI,CAClE,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,KAC5B,IAAI,CAAC;AAEV,MAAM,WAAW,iBAAiB;IAChC,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;CACrC;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,YAAY,EAAE,wBAAwB,CAAC;IAEhD,GAAG,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,EAAE,IAAI,EAAE,SAAS,GAAG,WAAW,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC9F,GAAG,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,MAAM,GAAG,WAAW,CAAC;IACzF,SAAS,CAAC,MAAM,SAAS,UAAU,GAAG,UAAU,EAC9C,IAAI,EAAE,SAAS,EACf,QAAQ,EAAE,aAAa,CAAC,MAAM,CAAC,GAC9B,WAAW,CAAC,iBAAiB,CAAC,CAAC;IAClC,MAAM,CAAC,CAAC,IAAI,EAAE,SAAS,GAAG,WAAW,CAAC;CACvC"}

package/dist/state.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=state.js.map

package/dist/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"","sourcesContent":["export type StatePrimitive = string | number | boolean | null;\n\nexport type StateValue =\n  | StatePrimitive\n  | readonly StateValue[]\n  | {\n      readonly [key: string]: StateValue;\n    };\n\nexport type StatePath = string | readonly string[];\n\nexport interface StateAdapterCapabilities {\n  readonly subscriptions: boolean;\n  readonly computed: boolean;\n  readonly persistence: boolean;\n}\n\nexport interface StateAdapterError {\n  readonly code: string;\n  readonly message: string;\n  readonly cause?: unknown;\n}\n\nexport type StateSuccess<TValue = void> = [TValue] extends [void]\n  ? {\n      readonly ok: true;\n    }\n  : {\n      readonly ok: true;\n      readonly data: TValue;\n    };\n\nexport type StateResult<TValue = void> =\n  | StateSuccess<TValue>\n  | {\n      readonly ok: false;\n      readonly error: StateAdapterError;\n    };\n\nexport interface StateSnapshot<TValue extends StateValue = StateValue> {\n  readonly path: StatePath;\n  readonly value: TValue | undefined;\n}\n\nexport type StateListener<TValue extends StateValue = StateValue> = (\n  snapshot: StateSnapshot<TValue>,\n) => void;\n\nexport interface StateSubscription {\n  unsubscribe(): Promise<void> | void;\n}\n\nexport interface StateAdapter {\n  readonly capabilities: StateAdapterCapabilities;\n\n  get<TValue extends StateValue = StateValue>(path: StatePath): StateResult<TValue | undefined>;\n  set<TValue extends StateValue = StateValue>(path: StatePath, value: TValue): StateResult;\n  subscribe<TValue extends StateValue = StateValue>(\n    path: StatePath,\n    listener: StateListener<TValue>,\n  ): StateResult<StateSubscription>;\n  delete?(path: StatePath): StateResult;\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ankhorage/contracts",
-  "version": "1.6.0",
+  "version": "1.7.0",
   "main": "./dist/index.js",
   "dependencies": {
     "@ankhorage/color-theory": "^0.0.7"
@@ -25,6 +25,10 @@
       "types": "./dist/db.d.ts",
       "default": "./dist/db.js"
     },
+    "./state": {
+      "types": "./dist/state.d.ts",
+      "default": "./dist/state.js"
+    },
     "./storage": {
       "types": "./dist/storage.d.ts",
       "default": "./dist/storage.js"

package/src/index.ts

@@ -1,4 +1,5 @@
 export * from './auth';
 export * from './db';
+export * from './state';
 export * from './storage';
 export * from './types';

package/src/state.test.ts

@@ -0,0 +1,188 @@
+import { describe, expect, it } from 'bun:test';
+
+import type {
+  StateAdapter,
+  StateListener,
+  StatePath,
+  StateResult,
+  StateSubscription,
+  StateValue,
+} from './state';
+
+function pathToKey(path: StatePath): string {
+  return Array.isArray(path) ? path.join('.') : path;
+}
+
+function isStateValue(value: unknown): value is StateValue {
+  if (value === null) {
+    return true;
+  }
+
+  if (typeof value === 'string' || typeof value === 'number' || typeof value === 'boolean') {
+    return true;
+  }
+
+  if (Array.isArray(value)) {
+    return value.every(isStateValue);
+  }
+
+  if (typeof value !== 'object') {
+    return false;
+  }
+
+  return Object.values(value).every(isStateValue);
+}
+
+function createError(code: string, message: string): StateResult {
+  return {
+    ok: false,
+    error: { code, message },
+  };
+}
+
+function createFakeStateAdapter(): StateAdapter {
+  const values = new Map<string, StateValue>();
+  const listeners = new Map<string, Set<StateListener>>();
+
+  const emit = (path: StatePath, value: StateValue | undefined) => {
+    const key = pathToKey(path);
+    const pathListeners = listeners.get(key);
+
+    if (!pathListeners) {
+      return;
+    }
+
+    for (const listener of pathListeners) {
+      listener({ path, value });
+    }
+  };
+
+  return {
+    capabilities: {
+      subscriptions: true,
+      computed: false,
+      persistence: false,
+    },
+    get(path) {
+      return { ok: true, data: values.get(pathToKey(path)) };
+    },
+    set(path, value) {
+      if (!isStateValue(value)) {
+        return createError('invalid_value', 'State value must be serializable.');
+      }
+
+      values.set(pathToKey(path), value);
+      emit(path, value);
+      return { ok: true };
+    },
+    subscribe(path, listener) {
+      const key = pathToKey(path);
+      const pathListeners = listeners.get(key) ?? new Set<StateListener>();
+      pathListeners.add(listener);
+      listeners.set(key, pathListeners);
+
+      const subscription: StateSubscription = {
+        unsubscribe() {
+          pathListeners.delete(listener);
+          if (pathListeners.size === 0) {
+            listeners.delete(key);
+          }
+        },
+      };
+
+      return { ok: true, data: subscription };
+    },
+    delete(path) {
+      values.delete(pathToKey(path));
+      emit(path, undefined);
+      return { ok: true };
+    },
+  };
+}
+
+describe('StateAdapter', () => {
+  it('supports path-based set and get', () => {
+    const adapter = createFakeStateAdapter();
+
+    const setResult = adapter.set(['forms', 'contact', 'values'], {
+      firstname: 'Fabio',
+      newsletter: true,
+    });
+    const getResult = adapter.get(['forms', 'contact', 'values']);
+
+    expect(setResult).toEqual({ ok: true });
+    expect(getResult).toEqual({
+      ok: true,
+      data: {
+        firstname: 'Fabio',
+        newsletter: true,
+      },
+    });
+  });
+
+  it('supports string paths and serializable nested values', () => {
+    const adapter = createFakeStateAdapter();
+    const value: StateValue = {
+      selectedIds: ['post-1', 'post-2'],
+      filters: {
+        search: 'hello',
+        onlyPublished: true,
+      },
+    };
+
+    adapter.set('collections.posts', value);
+
+    expect(adapter.get('collections.posts')).toEqual({ ok: true, data: value });
+  });
+
+  it('notifies subscribers when a value changes', () => {
+    const adapter = createFakeStateAdapter();
+    const snapshots: StateValue[] = [];
+    const subscriptionResult = adapter.subscribe('counter.value', ({ value }) => {
+      if (value !== undefined) {
+        snapshots.push(value);
+      }
+    });
+
+    adapter.set('counter.value', 1);
+    adapter.set('counter.value', 2);
+
+    expect(subscriptionResult.ok).toBe(true);
+    expect(snapshots).toEqual([1, 2]);
+  });
+
+  it('stops notifying after unsubscribe', async () => {
+    const adapter = createFakeStateAdapter();
+    const snapshots: StateValue[] = [];
+    const subscriptionResult = adapter.subscribe('counter.value', ({ value }) => {
+      if (value !== undefined) {
+        snapshots.push(value);
+      }
+    });
+
+    if (!subscriptionResult.ok) {
+      throw new Error('Expected subscription to succeed.');
+    }
+
+    adapter.set('counter.value', 1);
+    await subscriptionResult.data.unsubscribe();
+    adapter.set('counter.value', 2);
+
+    expect(snapshots).toEqual([1]);
+  });
+
+  it('supports deleting values when the adapter implements delete', () => {
+    const adapter = createFakeStateAdapter();
+    const snapshots: (StateValue | undefined)[] = [];
+    adapter.subscribe('session.user', ({ value }) => {
+      snapshots.push(value);
+    });
+
+    adapter.set('session.user', { id: 'user-1' });
+    const deleteResult = adapter.delete?.('session.user');
+
+    expect(deleteResult).toEqual({ ok: true });
+    expect(adapter.get('session.user')).toEqual({ ok: true, data: undefined });
+    expect(snapshots).toEqual([{ id: 'user-1' }, undefined]);
+  });
+});

package/src/state.ts

@@ -0,0 +1,63 @@
+export type StatePrimitive = string | number | boolean | null;
+
+export type StateValue =
+  | StatePrimitive
+  | readonly StateValue[]
+  | {
+      readonly [key: string]: StateValue;
+    };
+
+export type StatePath = string | readonly string[];
+
+export interface StateAdapterCapabilities {
+  readonly subscriptions: boolean;
+  readonly computed: boolean;
+  readonly persistence: boolean;
+}
+
+export interface StateAdapterError {
+  readonly code: string;
+  readonly message: string;
+  readonly cause?: unknown;
+}
+
+export type StateSuccess<TValue = void> = [TValue] extends [void]
+  ? {
+      readonly ok: true;
+    }
+  : {
+      readonly ok: true;
+      readonly data: TValue;
+    };
+
+export type StateResult<TValue = void> =
+  | StateSuccess<TValue>
+  | {
+      readonly ok: false;
+      readonly error: StateAdapterError;
+    };
+
+export interface StateSnapshot<TValue extends StateValue = StateValue> {
+  readonly path: StatePath;
+  readonly value: TValue | undefined;
+}
+
+export type StateListener<TValue extends StateValue = StateValue> = (
+  snapshot: StateSnapshot<TValue>,
+) => void;
+
+export interface StateSubscription {
+  unsubscribe(): Promise<void> | void;
+}
+
+export interface StateAdapter {
+  readonly capabilities: StateAdapterCapabilities;
+
+  get<TValue extends StateValue = StateValue>(path: StatePath): StateResult<TValue | undefined>;
+  set<TValue extends StateValue = StateValue>(path: StatePath, value: TValue): StateResult;
+  subscribe<TValue extends StateValue = StateValue>(
+    path: StatePath,
+    listener: StateListener<TValue>,
+  ): StateResult<StateSubscription>;
+  delete?(path: StatePath): StateResult;
+}