ink-framework-store 0.0.0-stage → 0.1.0-alpha.10

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vandam Dinh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/ink-native.json

@@ -0,0 +1,6 @@
+{
+  "version": 1,
+  "modules": {
+    "*": []
+  }
+}

package/package.json

@@ -1,6 +1,21 @@
 {
   "name": "ink-framework-store",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0-alpha.10",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "peerDependencies": {
+    "ink": "npm:ink-framework@0.1.0-alpha.10"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/No-Scrolling/ink.git",
+    "directory": "packages/store"
+  },
+  "files": [
+    "src",
+    "*.json",
+    "*.ts"
+  ]
+}

package/src/database.ts

@@ -0,0 +1,28 @@
+import { callNative } from "ink/native";
+
+export type SqlValue = string | number | null;
+export type SqlRow = Readonly<Record<string, SqlValue>>;
+
+export async function openDatabase(asset: string) {
+  const id = await callNative("sqlite", "open", { asset });
+  let closed = false;
+  let closing: Promise<void> | undefined;
+  return {
+    async query(sql: string, parameters: readonly SqlValue[] = [], options: { signal?: AbortSignal } = {}): Promise<readonly SqlRow[]> {
+      if (closed || closing) throw new Error("Database is closed");
+      if (parameters.some(value => value !== null && typeof value !== "string" && (typeof value !== "number" || !Number.isFinite(value)))) throw new TypeError("SQL parameters must be strings, finite numbers or null");
+      const result: unknown = JSON.parse(await callNative("sqlite", "query", { id, sql, parameters }, options));
+      if (!Array.isArray(result) || result.some(row => typeof row !== "object" || row === null || Array.isArray(row)
+        || Object.values(row).some(value => value !== null && typeof value !== "string" && typeof value !== "number"))) {
+        throw new Error("Invalid database result");
+      }
+      return result;
+    },
+    async close(): Promise<void> {
+      if (closed) return;
+      if (closing) return closing;
+      closing = callNative("sqlite", "close", { id }).then(() => { closed = true; });
+      try { await closing; } finally { closing = undefined; }
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,149 @@
+import type { Snapshot, SnapshotSource } from "ink";
+export { openDatabase, type SqlRow, type SqlValue } from "./database";
+import { callNative, onNativeMessage } from "ink/native";
+
+export interface Store<T> extends SnapshotSource<T> {
+  get(): Promise<T>;
+  set(value: T): Promise<void>;
+  update(transform: (value: T) => T): Promise<void>;
+  reset(): Promise<void>;
+}
+
+type Options<T> = {
+  key: string;
+  version: number;
+  initial: T;
+  decode(value: unknown): T;
+  migrate?: (value: unknown, version: number) => unknown;
+};
+type Entry = { revision: number; version: number; value: string };
+const observers = new Map<string, Set<() => void>>();
+onNativeMessage("store-changed", message => {
+  if (typeof message.key !== "string") throw new Error("Invalid store change event");
+  for (const observer of observers.get(message.key) ?? []) observer();
+});
+
+async function read(key: string): Promise<Entry | null> {
+  const result: unknown = JSON.parse(await callNative("store", "get", { key }));
+  if (result === null) return null;
+  if (typeof result !== "object" || !("revision" in result) || !("version" in result)
+    || !("value" in result) || typeof result.revision !== "number"
+    || !Number.isSafeInteger(result.revision) || result.revision < 1
+    || typeof result.version !== "number" || !Number.isSafeInteger(result.version)
+    || typeof result.value !== "string") throw new Error("Invalid stored entry");
+  return { revision: result.revision, version: result.version, value: result.value };
+}
+
+async function write(key: string, revision: number | null, version: number, value: unknown): Promise<boolean> {
+  const encoded = JSON.stringify(value);
+  if (encoded === undefined) throw new Error("Store values must be JSON data");
+  const result: unknown = JSON.parse(await callNative("store", revision === null ? "replace" : "write", { key, revision, version, value: encoded }));
+  if (typeof result !== "object" || result === null || !("committed" in result)
+    || typeof result.committed !== "boolean") throw new Error("Invalid store write result");
+  return result.committed;
+}
+
+export function createStore<T>(options: Options<T>): Store<T> {
+  const { key, version, decode } = options;
+  if (!key || key.length > 256 || !Number.isSafeInteger(version) || version < 1) {
+    throw new Error("Invalid store key or version");
+  }
+  let snapshot: Snapshot<T> = { status: "loading" };
+  const listeners = new Set<() => void>();
+  let loading: Promise<T> | undefined;
+  let generation = 0;
+
+  function publish(next: Snapshot<T>) {
+    snapshot = next;
+    for (const listener of listeners) listener();
+  }
+
+  function decodeEntry(entry: Entry | null): T {
+    if (!entry) return decode(options.initial);
+    if (entry.version > version) throw new Error(`Store ${key} uses a newer version`);
+    const value: unknown = JSON.parse(entry.value);
+    if (entry.version === version) return decode(value);
+    if (!options.migrate) throw new Error(`Store ${key} requires a migration`);
+    return decode(options.migrate(value, entry.version));
+  }
+
+  async function load(): Promise<T> {
+    for (let attempt = 0; attempt < 16; attempt++) {
+      const entry = await read(key);
+      const value = decodeEntry(entry);
+      if (!entry || entry.version === version) return value;
+      if (await write(key, entry.revision, version, value)) return value;
+    }
+    throw new Error(`Store ${key} changed too often; try again`);
+  }
+
+  function get(): Promise<T> {
+    if (loading) return loading;
+    const current = generation;
+    const promise = load().then(data => {
+      if (current === generation) publish({ status: "ready", data });
+      return data;
+    }, error => {
+      if (current === generation) publish({ status: "error", error: error instanceof Error ? error : new Error(String(error)) });
+      throw error;
+    }).finally(() => { if (loading === promise) loading = undefined; });
+    loading = promise;
+    return loading;
+  }
+
+  function refresh() {
+    generation++;
+    loading = undefined;
+    void get().catch(() => {});
+  }
+
+  function changed(value: T) {
+    generation++;
+    loading = undefined;
+    publish({ status: "ready", data: value });
+    for (const observer of observers.get(key) ?? []) observer();
+  }
+
+  async function replace(value: T) {
+    const decoded = decode(value);
+    if (await write(key, null, version, decoded)) changed(decoded);
+  }
+
+  async function mutate(transform: (entry: Entry | null) => T) {
+    for (let attempt = 0; attempt < 16; attempt++) {
+      const entry = await read(key);
+      if (entry && entry.version > version) throw new Error(`Store ${key} uses a newer version`);
+      const value = decode(transform(entry));
+      if (await write(key, entry?.revision ?? 0, version, value)) {
+        changed(value);
+        return;
+      }
+    }
+    throw new Error(`Store ${key} changed too often; try again`);
+  }
+
+  return {
+    get,
+    set: replace,
+    update: transform => mutate(entry => transform(decodeEntry(entry))),
+    reset: () => replace(options.initial),
+    getSnapshot: () => snapshot,
+    subscribe(listener) {
+      listeners.add(listener);
+      if (listeners.size === 1) {
+        let group = observers.get(key);
+        if (!group) observers.set(key, group = new Set());
+        group.add(refresh);
+        refresh();
+      }
+      return () => {
+        listeners.delete(listener);
+        if (!listeners.size) {
+          const group = observers.get(key);
+          group?.delete(refresh);
+          if (!group?.size) observers.delete(key);
+        }
+      };
+    },
+  };
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.