{"version":3,"file":"storage-client-3FCa7guy.mjs","names":[],"sources":["../src/storage/storage-client.ts"],"sourcesContent":["/* SPDX-FileCopyrightText: 2026 Espressif Systems (Shanghai) CO LTD */\n/* SPDX-License-Identifier: Apache-2.0 */\n\nimport {\n  callServiceFunction,\n  closeService,\n  isServiceAvailable,\n  openService,\n  resolveHost,\n  type ServiceClientOptions,\n  type ServiceHandle,\n} from '../common/service-rpc.js';\nimport type {\n  FileEntry,\n  FileInfo,\n  FileSystemCapacity,\n  FileSystemInfo,\n  KvNameResult,\n  StorageEntryInfo,\n  StorageKeyValueMap,\n} from './storage-types.js';\n\n/** Registered name (`helper::Storage::get_name()`). */\nexport const STORAGE_SERVICE_NAME = 'Storage';\n\n/** Default namespace when omitted on the device (`helper::Storage::DEFAULT_NAMESPACE`). */\nexport const STORAGE_DEFAULT_NAMESPACE = 'storage';\n\n/** RPC function names (`helper::Storage::FunctionId`). */\nexport const STORAGE_FUNCTIONS = {\n  KVList: 'KVList',\n  KVSet: 'KVSet',\n  KVGet: 'KVGet',\n  KVErase: 'KVErase',\n  GetFileSystems: 'GetFileSystems',\n  GetFileSystemCapacity: 'GetFileSystemCapacity',\n  FSStat: 'FSStat',\n  FSList: 'FSList',\n  FSMkdir: 'FSMkdir',\n  FSReadText: 'FSReadText',\n  FSWriteText: 'FSWriteText',\n  FSRemove: 'FSRemove',\n  FSRename: 'FSRename',\n  FSCopyTree: 'FSCopyTree',\n  MakeKVKey: 'MakeKVKey',\n  MakeKVNamespace: 'MakeKVNamespace',\n} as const;\n\nexport type {\n  StorageEntryInfo,\n  StorageKeyValueMap,\n  StorageValue,\n  StorageValueType,\n} from './storage-types.js';\nexport type {\n  FileEntry,\n  FileInfo,\n  FileSystemInfo,\n  FileSystemCapacity,\n  KvNameResult,\n} from './storage-types.js';\n\nexport type StorageClientOptions = ServiceClientOptions;\n\nexport { type ServiceHandle as StorageHandle };\n\n/** Check whether the Storage service is registered on the device. */\nexport function isStorageAvailable(options?: StorageClientOptions): boolean {\n  return isServiceAvailable(STORAGE_SERVICE_NAME, options);\n}\n\n/** Bind the Storage service for the current app context. */\nexport function openStorage(options?: StorageClientOptions): ServiceHandle {\n  return openService(STORAGE_SERVICE_NAME, options);\n}\n\n/** Release a handle from {@link openStorage}. */\nexport function closeStorage(handle: ServiceHandle, options?: StorageClientOptions): void {\n  closeService(handle, options);\n}\n\nfunction callStorage<T>(\n  handle: ServiceHandle,\n  functionName: string,\n  params: Record<string, unknown>,\n  options?: StorageClientOptions,\n): T {\n  return callServiceFunction<T>(resolveHost(options), handle, functionName, params);\n}\n\n// ── KV operations ──────────────────────────────────────────────\n\n/** List entries in a Storage KV namespace. */\nexport function kvList(\n  handle: ServiceHandle,\n  nspace: string = STORAGE_DEFAULT_NAMESPACE,\n  options?: StorageClientOptions,\n): StorageEntryInfo[] {\n  return callStorage<StorageEntryInfo[]>(\n    handle,\n    STORAGE_FUNCTIONS.KVList,\n    { Nspace: nspace },\n    options,\n  );\n}\n\n/** Write key-value pairs into a Storage KV namespace. */\nexport function kvSet(\n  handle: ServiceHandle,\n  nspace: string,\n  keyValuePairs: StorageKeyValueMap,\n  options?: StorageClientOptions,\n): void {\n  callStorage<void>(\n    handle,\n    STORAGE_FUNCTIONS.KVSet,\n    { Nspace: nspace, KeyValuePairs: keyValuePairs },\n    options,\n  );\n}\n\n/**\n * Read keys from a Storage KV namespace.\n * When `keys` is omitted or empty, the device returns all pairs in the namespace.\n */\nexport function kvGet(\n  handle: ServiceHandle,\n  nspace: string,\n  keys?: string[],\n  options?: StorageClientOptions,\n): StorageKeyValueMap {\n  return callStorage<StorageKeyValueMap>(\n    handle,\n    STORAGE_FUNCTIONS.KVGet,\n    { Nspace: nspace, Keys: keys ?? [] },\n    options,\n  );\n}\n\n/**\n * Erase keys from a Storage KV namespace.\n * When `keys` is omitted or empty, the device erases all pairs in the namespace.\n */\nexport function kvErase(\n  handle: ServiceHandle,\n  nspace: string,\n  keys?: string[],\n  options?: StorageClientOptions,\n): void {\n  callStorage<void>(\n    handle,\n    STORAGE_FUNCTIONS.KVErase,\n    { Nspace: nspace, Keys: keys ?? [] },\n    options,\n  );\n}\n\n// ── File system operations ─────────────────────────────────────\n\n/** List mounted storage file systems. */\nexport function getFileSystems(\n  handle: ServiceHandle,\n  options?: StorageClientOptions,\n): FileSystemInfo[] {\n  return callStorage<FileSystemInfo[]>(handle, STORAGE_FUNCTIONS.GetFileSystems, {}, options);\n}\n\n/** Get capacity info for one mounted file system. */\nexport function getFileSystemCapacity(\n  handle: ServiceHandle,\n  mountPoint: string,\n  options?: StorageClientOptions,\n): FileSystemCapacity {\n  return callStorage<FileSystemCapacity>(\n    handle,\n    STORAGE_FUNCTIONS.GetFileSystemCapacity,\n    { MountPoint: mountPoint },\n    options,\n  );\n}\n\n/** Stat a file-system path (get type, size, mtime). */\nexport function fsStat(\n  handle: ServiceHandle,\n  path: string,\n  options?: StorageClientOptions,\n): FileInfo {\n  return callStorage<FileInfo>(handle, STORAGE_FUNCTIONS.FSStat, { Path: path }, options);\n}\n\n/** List direct children under a file-system directory. */\nexport function fsList(\n  handle: ServiceHandle,\n  path: string,\n  options?: StorageClientOptions,\n): FileEntry[] {\n  return callStorage<FileEntry[]>(handle, STORAGE_FUNCTIONS.FSList, { Path: path }, options);\n}\n\n/** Create a directory (mkdir -p). */\nexport function fsMkdir(handle: ServiceHandle, path: string, options?: StorageClientOptions): void {\n  callStorage<void>(handle, STORAGE_FUNCTIONS.FSMkdir, { Path: path }, options);\n}\n\n/** Read a text file from a mounted file system. */\nexport function fsReadText(\n  handle: ServiceHandle,\n  path: string,\n  options?: StorageClientOptions,\n): string {\n  return callStorage<string>(handle, STORAGE_FUNCTIONS.FSReadText, { Path: path }, options);\n}\n\n/** Write a text file to a mounted file system. */\nexport function fsWriteText(\n  handle: ServiceHandle,\n  path: string,\n  data: string,\n  options?: StorageClientOptions,\n): void {\n  callStorage<void>(handle, STORAGE_FUNCTIONS.FSWriteText, { Path: path, Data: data }, options);\n}\n\n/** Remove a file or empty directory from a mounted file system. */\nexport function fsRemove(\n  handle: ServiceHandle,\n  path: string,\n  options?: StorageClientOptions,\n): void {\n  callStorage<void>(handle, STORAGE_FUNCTIONS.FSRemove, { Path: path }, options);\n}\n\n/** Rename (move) a file or directory. */\nexport function fsRename(\n  handle: ServiceHandle,\n  from: string,\n  to: string,\n  options?: StorageClientOptions,\n): void {\n  callStorage<void>(handle, STORAGE_FUNCTIONS.FSRename, { From: from, To: to }, options);\n}\n\n/** Recursively copy a file or directory tree. */\nexport function fsCopyTree(\n  handle: ServiceHandle,\n  from: string,\n  to: string,\n  overwrite: boolean,\n  options?: StorageClientOptions,\n): void {\n  callStorage<void>(\n    handle,\n    STORAGE_FUNCTIONS.FSCopyTree,\n    { From: from, To: to, Overwrite: overwrite },\n    options,\n  );\n}\n\n// ── KV name utilities ──────────────────────────────────────────\n\n/** Generate a KV key that satisfies the backend limits. */\nexport function makeKvKey(\n  handle: ServiceHandle,\n  parts: string[],\n  separator = '.',\n  options?: StorageClientOptions,\n): KvNameResult {\n  return callStorage<KvNameResult>(\n    handle,\n    STORAGE_FUNCTIONS.MakeKVKey,\n    { Parts: parts, Separator: separator },\n    options,\n  );\n}\n\n/** Generate a KV namespace that satisfies the backend limits. */\nexport function makeKvNamespace(\n  handle: ServiceHandle,\n  parts: string[],\n  separator = '.',\n  options?: StorageClientOptions,\n): KvNameResult {\n  return callStorage<KvNameResult>(\n    handle,\n    STORAGE_FUNCTIONS.MakeKVNamespace,\n    { Parts: parts, Separator: separator },\n    options,\n  );\n}\n\n// ── Lifecycle helper ───────────────────────────────────────────\n\n/**\n * Run `fn` with a Storage handle that is always closed in a `finally` block.\n */\nexport async function withStorage<T>(\n  fn: (handle: ServiceHandle) => T | Promise<T>,\n  options?: StorageClientOptions,\n): Promise<T> {\n  const handle = openStorage(options);\n  try {\n    return await fn(handle);\n  } finally {\n    closeStorage(handle, options);\n  }\n}\n"],"mappings":"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"}