@legendapp/spark 0.0.1-next.2 → 0.0.1-next.4

package/vendor/node_modules/@legendapp/spark-secure-storage/src/options.ts

@@ -1,6 +1,7 @@
+import { SparkError } from "@legendapp/spark-desktop-app/src/contracts";
 /** Only default storage is portable today. Authentication/service overrides are not implemented. */
 export type SecureStoreOptions = Record<string, never>;
 export function validateItem(key: string, options: SecureStoreOptions) {
-  if (typeof key !== "string" || !/^[\w.-]+$/.test(key) || key.length > 200) throw new Error("SecureStore keys must be 1–200 alphanumeric, '.', '-', or '_' characters");
-  if (!options || Object.keys(options).length) throw Object.assign(new Error("SecureStore options are not supported by the shared API yet"), { code: "E_UNSUPPORTED_OPTION" });
+  if (typeof key !== "string" || !/^[\w.-]+$/.test(key) || key.length > 200) throw new SparkError("E_INVALID_ARGUMENT", "SecureStore keys must be 1–200 alphanumeric, '.', '-', or '_' characters");
+  if (!options || typeof options !== "object" || Array.isArray(options) || Object.keys(options).length) throw new SparkError("E_UNSUPPORTED_OPTION", "SecureStore options are not supported by the shared API");
 }

package/vendor/node_modules/@legendapp/spark-secure-storage/src/unavailable.ts

@@ -1,5 +1,8 @@
+import { SparkError } from "@legendapp/spark-desktop-app/src/contracts";
+import type { SecureStoreOptions } from "./options";
 export type { SecureStoreOptions } from "./options";
 export async function isAvailableAsync(): Promise<boolean> { return false; }
-const unavailable = async (..._args: unknown[]): Promise<never> => { throw Object.assign(new Error("Secure storage is unavailable on this platform"), { code: "E_UNAVAILABLE" }); };
-export const getItemAsync = unavailable, setItemAsync = unavailable, deleteItemAsync = unavailable;
-export const secureStorage = { get: getItemAsync, set: setItemAsync, remove: deleteItemAsync };
+function unavailable(): never { throw new SparkError("E_UNSUPPORTED_PLATFORM", "Secure storage is unavailable on this platform"); }
+export async function getItemAsync(_key: string, _options?: SecureStoreOptions): Promise<string | null> { return unavailable(); }
+export async function setItemAsync(_key: string, _value: string, _options?: SecureStoreOptions): Promise<void> { return unavailable(); }
+export async function deleteItemAsync(_key: string, _options?: SecureStoreOptions): Promise<void> { return unavailable(); }

package/vendor/node_modules/@legendapp/spark-settings/package.json

@@ -1,13 +1,20 @@
 {
   "name": "@legendapp/spark-settings",
-  "version": "0.0.1-next.2",
+  "version": "0.0.1-next.4",
   "license": "MIT",
   "main": "src/index.ts",
   "files": [
     "src"
   ],
   "dependencies": {
-    "@legendapp/spark-file-system": "0.0.1-next.2"
+    "@legendapp/spark-file-system": "0.0.1-next.4",
+    "@legendapp/state": "^3.0.0-beta.42",
+    "@legendapp/spark-desktop-app": "0.0.1-next.4"
   },
-  "private": true
+  "private": true,
+  "spark": {
+    "sdk": true
+  },
+  "peerDependencies": {},
+  "peerDependenciesMeta": {}
 }

package/vendor/node_modules/@legendapp/spark-settings/src/fileStorage.ts

@@ -0,0 +1,11 @@
+import type { SettingsStorage } from "./store";
+/** Loaded lazily so custom backends and observable types do not require a native host. */
+export const fileStorage: SettingsStorage = {
+  async read(path) {
+    const files = await import("@legendapp/spark-file-system");
+    try { return await files.readText(path); }
+    catch (error) { if ((error as { code?: string }).code === "E_NOT_FOUND") return undefined; throw error; }
+  },
+  async write(path, value) { await (await import("@legendapp/spark-file-system")).writeText(path, value); },
+  async remove(path) { await (await import("@legendapp/spark-file-system")).remove(path); },
+};

package/vendor/node_modules/@legendapp/spark-settings/src/index.ts

@@ -1,7 +1,8 @@
 import * as files from "@legendapp/spark-file-system";
 import { settingsFilename } from "./filename";
 import { createSettingsStore } from "./store";
-export { createSettingsStore, type Json, type SettingsStorage } from "./store";
+import { fileStorage } from "./fileStorage";
+export { createSettingsStore, type Json, type SettingsStorage, type SettingsStore, type SettingsStoreOptions, type SettingsReadOptions } from "./store";
 let directory: Promise<string> | undefined;
 async function file(key: string) {
   directory ??= files.getDirectory("data").then(async root => {
@@ -9,11 +10,8 @@ async function file(key: string) {
   }).catch(error => { directory = undefined; throw error; });
   return `${await directory}/${settingsFilename(key)}`;
 }
-export const settings = createSettingsStore({
-  async read(key) {
-    try { return await files.readText(await file(key)); }
-    catch (error) { if ((error as { code?: string }).code === "E_NOT_FOUND") return null; throw error; }
-  },
-  async write(key, value) { await files.writeText(await file(key), value); },
-  async remove(key) { await files.remove(await file(key)); },
-});
+export const settings = createSettingsStore({ storage: {
+  async read(key) { return fileStorage.read(await file(key)); },
+  async write(key, value) { await fileStorage.write(await file(key), value); },
+  async remove(key) { await fileStorage.remove(await file(key)); },
+} });

package/vendor/node_modules/@legendapp/spark-settings/src/storage/index.ts

@@ -0,0 +1,142 @@
+import { internal, observable, type Observable } from "@legendapp/state";
+import { SparkError } from "@legendapp/spark-desktop-app/src/contracts";
+import { absolutePath } from "@legendapp/spark-desktop-app/src/contracts/path";
+import type { SettingsStorage } from "../store";
+import { fileStorage } from "../fileStorage";
+
+export interface ObservableFileOptions<T> {
+  /** Absolute native path, including the extension. Parent directory must exist. */
+  path: string;
+  initialValue: T;
+  /** Validate/convert persisted data. Missing files use initialValue. */
+  decode(value: unknown): T | Promise<T>;
+  /** Convert a snapshot for persistence. Omit to use Legend State serialization. */
+  encode?(value: T): unknown | Promise<unknown>;
+  storage?: SettingsStorage;
+  debounceMs?: number;
+  saveDefault?: boolean;
+}
+export interface ObservableFile<T> {
+  /** Legend State owns this observable API. Mutations after close are not persisted. */
+  value$: Observable<T>;
+  /** Most recent persistence failure; cleared after a successful save. */
+  error$: Observable<Error | undefined>;
+  /** Save a snapshot of all changes made before this call, including inside batches. */
+  flush(): Promise<void>;
+  /** Stop automatic saves immediately and flush a final snapshot. Failed closes retry. */
+  close(): Promise<void>;
+}
+function stringify(value: unknown): string | undefined {
+  if (value === undefined) return undefined;
+  // Legend's helper returns falsy input unchanged. File storage always needs text.
+  const text = value ? internal.safeStringify(value) : JSON.stringify(value);
+  if (typeof text !== "string") throw new SparkError("E_INVALID_DATA", "Value cannot be serialized");
+  return text;
+}
+function parse(text: string | undefined): unknown {
+  if (text === undefined) return undefined;
+  if (typeof text !== "string" || text.length === 0) throw new SparkError("E_INVALID_DATA", "Expected serialized settings");
+  return internal.safeParse(text);
+}
+
+/** Await readiness before editing. Load/decode failures preserve existing bytes.
+ * Writes are serialized within this handle, not across handles or processes.
+ * Root undefined removes the file; null is persisted. Date/Map/Set use Legend encoding.
+ */
+export async function createObservableFile<T>(options: ObservableFileOptions<T>): Promise<ObservableFile<T>> {
+  if (!options || typeof options !== "object" || Array.isArray(options)) throw new SparkError("E_INVALID_ARGUMENT", "Expected observable file options");
+  for (const key of Object.keys(options)) if (!["path", "initialValue", "decode", "encode", "storage", "debounceMs", "saveDefault"].includes(key)) throw new SparkError("E_UNSUPPORTED_OPTION", `Unsupported observable file option: ${key}`);
+  const path = absolutePath(options.path, typeof options.path === "string" && options.path.startsWith("/") ? "macos" : "windows");
+  const { decode, encode, storage = fileStorage, debounceMs = 300, saveDefault = false } = options;
+  if (typeof decode !== "function" || (encode !== undefined && typeof encode !== "function")) throw new SparkError("E_INVALID_ARGUMENT", "Expected a decoder and optional encoder");
+  if (!Number.isFinite(debounceMs) || debounceMs < 0 || debounceMs > 2147483647 || typeof saveDefault !== "boolean") throw new SparkError("E_INVALID_ARGUMENT", "Invalid persistence timing options");
+  if (!storage || [storage.read, storage.write, storage.remove].some(method => typeof method !== "function")) throw new SparkError("E_INVALID_ARGUMENT", "Expected read/write/remove storage methods");
+  const text = await storage.read(path);
+  let initial: T;
+  try { initial = text === undefined ? parse(stringify(options.initialValue)) as T : await decode(parse(text)); }
+  catch (cause) { throw new SparkError("E_INVALID_DATA", "Could not decode observable file", { cause }); }
+  const value$ = observable(initial) as Observable<T>;
+  const error$ = observable<Error | undefined>();
+  const recordError = (error: unknown) => error$.set(error instanceof Error ? error : new SparkError("E_NATIVE", "Persistence failed", { cause: error }));
+  let persisted = stringify(initial);
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  let queue: Promise<void> = Promise.resolve();
+  let closing = false, closed = false;
+  let closingSnapshot: string | undefined;
+  let capturedClose = false;
+  let closePromise: Promise<void> | undefined;
+  const clearTimer = () => { if (timer !== undefined) clearTimeout(timer); timer = undefined; };
+  function snapshot(): string | undefined { return stringify(value$.peek()); }
+  function save(snapshotText: string | undefined, force = false): Promise<void> {
+    const next = queue.catch(() => {}).then(async () => {
+      if (force || persisted !== snapshotText) {
+        // The serialized snapshot is already isolated from later observable mutations.
+        const output = encode ? stringify(await encode(parse(snapshotText) as T)) : snapshotText;
+        if (output === undefined) await storage.remove(path);
+        else await storage.write(path, output);
+        persisted = snapshotText;
+      }
+      error$.set(undefined);
+    }).catch(error => { recordError(error); throw error; });
+    queue = next;
+    // Automatic writes report through error$; explicit callers still receive rejection.
+    void next.catch(() => {});
+    return next;
+  }
+  const unsubscribe = value$.onChange(() => {
+    if (closing) return;
+    clearTimer();
+    timer = setTimeout(() => {
+      timer = undefined;
+      try { void save(snapshot()); } catch (error) { recordError(error); }
+    }, debounceMs);
+  }, { immediate: true });
+  const handle: ObservableFile<T> = {
+    value$, error$,
+    async flush() {
+      if (closing) throw new SparkError("E_CLOSED", "Observable file is closing or closed");
+      clearTimer();
+      try { await save(snapshot()); } catch (error) { recordError(error); throw error; }
+    },
+    close() {
+      if (closed) return Promise.resolve();
+      if (closePromise) return closePromise;
+      closing = true; clearTimer(); unsubscribe();
+      // Capture synchronously, before consumers can mutate after calling close.
+      try { if (!capturedClose) { closingSnapshot = snapshot(); capturedClose = true; } }
+      catch (error) { recordError(error); return Promise.reject(error); }
+      closePromise = save(closingSnapshot).then(() => { closed = true; }).finally(() => { closePromise = undefined; });
+      return closePromise;
+    },
+  };
+  if (saveDefault && text === undefined) {
+    try { await save(persisted, true); }
+    catch (error) { unsubscribe(); throw error; }
+  }
+  return handle;
+}
+
+export interface ObservableSettingsField<T> {
+  defaultValue: T;
+  decode(value: unknown): T;
+}
+export type ObservableSettingsFields = Record<string, ObservableSettingsField<any>>;
+export type ObservableSettingsValues<F extends ObservableSettingsFields> = { [K in keyof F]: F[K] extends ObservableSettingsField<infer T> ? T : never };
+export interface ObservableSettingsOptions<F extends ObservableSettingsFields> extends Omit<ObservableFileOptions<ObservableSettingsValues<F>>, "initialValue" | "decode" | "encode"> { fields: F }
+/** Field defaults apply only to absent fields; stored null is passed to the decoder.
+ * Unknown fields are omitted. Use value$.field directly with Legend State's useValue.
+ */
+export async function createObservableSettings<const F extends ObservableSettingsFields>(options: ObservableSettingsOptions<F>): Promise<ObservableFile<ObservableSettingsValues<F>>> {
+  if (!options || !options.fields || typeof options.fields !== "object" || Array.isArray(options.fields)) throw new SparkError("E_INVALID_ARGUMENT", "Expected settings fields");
+  const { fields, ...rest } = options;
+  const entries = Object.entries(fields);
+  if (entries.some(([, field]) => !field || typeof field.decode !== "function")) throw new SparkError("E_INVALID_ARGUMENT", "Each field requires a decoder");
+  return createObservableFile({
+    ...rest,
+    initialValue: Object.fromEntries(entries.map(([key, field]) => [key, field.defaultValue])) as ObservableSettingsValues<F>,
+    decode(value) {
+      if (!value || typeof value !== "object" || Array.isArray(value)) throw new SparkError("E_INVALID_DATA", "Expected a settings object");
+      return Object.fromEntries(entries.map(([key, field]) => [key, Object.hasOwn(value, key) ? field.decode((value as Record<string, unknown>)[key]) : field.defaultValue])) as ObservableSettingsValues<F>;
+    },
+  });
+}

package/vendor/node_modules/@legendapp/spark-settings/src/store.ts

@@ -1,35 +1,77 @@
+import { SparkError } from "@legendapp/spark-desktop-app/src/contracts";
 export type Json = null | boolean | number | string | Json[] | { [key: string]: Json };
-export type SettingsStorage = { read(key: string): Promise<string | null>; write(key: string, value: string): Promise<void>; remove(key: string): Promise<void> };
-function serialize(value: Json): string {
-  return JSON.stringify(value, (_key, item: unknown) => {
-    if (item === undefined || typeof item === "function" || typeof item === "symbol" || typeof item === "bigint" ||
-        (typeof item === "number" && !Number.isFinite(item))) throw new Error("Settings must contain finite JSON values");
-    return item;
-  });
+export interface SettingsStorage {
+  read(key: string): Promise<string | undefined>;
+  write(key: string, value: string): Promise<void>;
+  remove(key: string): Promise<void>;
 }
-/** Mutations are serialized per key, including failed updates. Await writes before quitting. */
-export function createSettingsStore(storage: SettingsStorage) {
+export interface SettingsStoreOptions { storage: SettingsStorage }
+export interface SettingsReadOptions<T> { decode(value: Json): T }
+export interface SettingsStore {
+  get(key: string): Promise<Json | undefined>;
+  get<T>(key: string, options: SettingsReadOptions<T>): Promise<T | undefined>;
+  set(key: string, value: Json): Promise<void>;
+  remove(key: string): Promise<void>;
+  update<T extends Json>(key: string, updater: (value: Json | undefined) => T | Promise<T>): Promise<T>;
+}
+function validateJson(value: unknown, ancestors = new Set<object>()): void {
+  if (value === null || typeof value === "boolean" || typeof value === "string") return;
+  if (typeof value === "number" && Number.isFinite(value)) return;
+  if (typeof value !== "object" || !value || ancestors.has(value) || (!Array.isArray(value) && Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null)) throw new SparkError("E_INVALID_ARGUMENT", "Settings must contain finite JSON values without cycles");
+  ancestors.add(value);
+  try {
+    if (Array.isArray(value)) { for (const item of value) validateJson(item, ancestors); return; }
+    if (Object.getOwnPropertySymbols(value).length) throw new SparkError("E_INVALID_ARGUMENT", "Settings cannot have symbol keys");
+    for (const key of Object.keys(value)) validateJson((value as Record<string, unknown>)[key], ancestors);
+  } finally { ancestors.delete(value); }
+}
+// Serialization itself snapshots before the operation can wait in the per-key queue.
+const serialize = (value: Json) => { validateJson(value); return JSON.stringify(value); };
+function validateParsedNumbers(value: Json): void {
+  if (typeof value === "number" && !Number.isFinite(value)) throw new SparkError("E_INVALID_DATA", "Stored settings contain non-finite numbers");
+  if (Array.isArray(value)) { for (const item of value) validateParsedNumbers(item); }
+  else if (value && typeof value === "object") for (const key of Object.keys(value)) validateParsedNumbers(value[key]);
+}
+/** This store serializes operations per key. It does not lock other stores/processes.
+ * Updaters must not await another operation on the same key in this store. */
+export function createSettingsStore(options: SettingsStoreOptions): SettingsStore {
+  if (!options || typeof options !== "object" || Array.isArray(options)) throw new SparkError("E_INVALID_ARGUMENT", "Expected settings store options");
+  if (Object.keys(options).some(key => key !== "storage")) throw new SparkError("E_UNSUPPORTED_OPTION", "Unsupported settings store option");
+  const { storage } = options;
+  if (!storage || [storage.read, storage.write, storage.remove].some(method => typeof method !== "function")) throw new SparkError("E_INVALID_ARGUMENT", "Expected read/write/remove storage methods");
   const pending = new Map<string, Promise<unknown>>();
-  const validate = (key: string) => { if (!key.length || key.length > 200) throw new Error("Setting keys must contain 1–200 characters"); };
   function enqueue<T>(key: string, operation: () => Promise<T>): Promise<T> {
-    validate(key);
-    const next = (pending.get(key) ?? Promise.resolve()).catch(() => {}).then(operation);
+    if (typeof key !== "string" || !key.length || key.length > 200 || key.includes("\0")) throw new SparkError("E_INVALID_ARGUMENT", "Setting keys must contain 1–200 characters without NUL");
+    const previous = pending.get(key);
+    let next: Promise<T>;
+    try { next = previous ? previous.then(operation, operation) : operation(); }
+    catch (error) { next = Promise.reject(error); }
     pending.set(key, next);
-    void next.finally(() => { if (pending.get(key) === next) pending.delete(key); }).catch(() => {});
+    const settled = () => { if (pending.get(key) === next) pending.delete(key); };
+    void next.then(settled, settled);
     return next;
   }
-  async function read<T extends Json>(key: string): Promise<T | null> {
+  async function read(key: string): Promise<Json | undefined> {
     const value = await storage.read(key);
-    // Corruption is an error; never silently replace it with defaults.
-    return value === null ? null : JSON.parse(value) as T;
+    if (value === undefined) return undefined;
+    if (typeof value !== "string") throw new SparkError("E_INVALID_DATA", "Storage reads must return text or undefined");
+    try { const parsed = JSON.parse(value) as Json; validateParsedNumbers(parsed); return parsed; }
+    catch (cause) { throw new SparkError("E_INVALID_DATA", "Stored settings are not valid JSON", { cause }); }
+  }
+  async function get(key: string): Promise<Json | undefined>;
+  async function get<T>(key: string, options: SettingsReadOptions<T>): Promise<T | undefined>;
+  async function get<T>(key: string, options?: SettingsReadOptions<T>): Promise<Json | T | undefined> {
+    if (options !== undefined && (!options || typeof options.decode !== "function" || Object.keys(options).some(key => key !== "decode"))) throw new SparkError("E_INVALID_ARGUMENT", "Expected a settings decoder");
+    return enqueue(key, async () => { const value = await read(key); return value === undefined || !options ? value : options.decode(value); });
   }
   return {
-    get<T extends Json>(key: string) { return enqueue(key, () => read<T>(key)); },
-    set(key: string, value: Json) { const json = serialize(value); return enqueue(key, () => storage.write(key, json)); },
-    remove(key: string) { return enqueue(key, () => storage.remove(key)); },
-    update<T extends Json>(key: string, update: (value: T | null) => T | Promise<T>) {
+    get,
+    async set(key, value) { const json = serialize(value); await enqueue(key, () => storage.write(key, json)); },
+    async remove(key) { await enqueue(key, () => storage.remove(key)); },
+    async update(key, updater) {
+      if (typeof updater !== "function") throw new SparkError("E_INVALID_ARGUMENT", "Expected a settings updater");
       return enqueue(key, async () => {
-        const value = await update(await read<T>(key));
+        const value = await updater(await read(key));
         await storage.write(key, serialize(value)); return value;
       });
     },

package/vendor/node_modules/@legendapp/spark-settings-ui/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@legendapp/spark-settings-ui",
+  "version": "0.0.1-next.4",
+  "private": true,
+  "license": "MIT",
+  "main": "src/index.tsx",
+  "files": [
+    "src"
+  ],
+  "dependencies": {
+    "@legendapp/spark-ui": "0.0.1-next.4",
+    "@legendapp/spark-desktop-windows": "0.0.1-next.4",
+    "@legendapp/spark-desktop-app": "0.0.1-next.4"
+  },
+  "peerDependencies": {
+    "react": "19.1.4",
+    "react-native": "0.81.6",
+    "@legendapp/list": ">=3.3.0"
+  }
+}