akanjs 3.0.0-beta.20 → 3.0.0-beta.21

package/vendor/@akanjs/native/plugins/filesystem/src/index.ts

@@ -0,0 +1,179 @@
+import {
+  AkanNativeError,
+  definePlugin,
+  type FileRef,
+  type Plugin,
+  platform,
+} from "../../../packages/core/src/index.ts";
+import { bytesToBase64, fileRefId } from "./common.ts";
+import { web } from "./web.ts";
+
+/**
+ * Where a path lives. Paths are always relative to one of these; absolute paths and ".." are
+ * rejected with INVALID_ARGS, and symbolic links that lead outside the base with PERMISSION_DENIED.
+ *
+ * | base      | macOS                                   | iOS                                | Android                                        | web (OPFS) |
+ * |-----------|-----------------------------------------|------------------------------------|------------------------------------------------|------------|
+ * | data      | ~/Library/Application Support/<id>/files | Library/Application Support/files | files/ (Context.filesDir)                      | /data      |
+ * | cache     | ~/Library/Caches/<id>/files             | Library/Caches/files               | cache/files                                    | /cache     |
+ * | documents | ~/Documents                             | Documents                          | Android/data/<id>/files/Documents (external)   | /documents |
+ * | temp      | $TMPDIR/<id>/files                      | tmp/files                          | cache/temp                                     | /temp      |
+ *
+ * - data: kept until the app is removed, included in device backups.
+ * - cache, temp: the OS may delete them when storage runs low (iOS, Android) or at any time the app
+ *   is not running (iOS tmp). Not backed up.
+ * - documents: user-visible documents. On macOS the first access asks the user for the Documents
+ *   folder (TCC). On iOS the Files app shows it only if the app's Info.plist sets
+ *   UIFileSharingEnabled and LSSupportsOpeningDocumentsInPlace. On Android it is the app's own
+ *   external folder: no permission, removed with the app.
+ * - web: the origin private file system (navigator.storage.getDirectory()), one folder per base.
+ */
+export type BaseDirectory = "data" | "cache" | "documents" | "temp";
+export type Encoding = "utf8" | "base64";
+export type EntryType = "file" | "directory" | "symlink" | "other";
+
+export interface PathOptions {
+  /** Relative to `base`, "/"-separated, e.g. "notes/today.txt". */
+  path: string;
+  base: BaseDirectory;
+}
+
+export interface ReadFileOptions extends PathOptions {
+  /**
+   * "utf8" returns the text, "base64" the bytes as base64. Without an encoding the file is not
+   * sent over the bridge at all: the result is a FileRef whose `url` serves the file (fetch it,
+   * or use it as an <img>/<video> src), which is the way to read large or binary files.
+   */
+  encoding?: Encoding;
+}
+
+export type WriteFileOptions = PathOptions & {
+  /** Add to the end of the file instead of replacing it. Replacing writes are atomic (temp file + rename). */
+  append?: boolean;
+  /** Create missing parent folders. Without it a missing parent rejects NOT_FOUND. */
+  recursive?: boolean;
+} & (
+    | {
+        /** Text, or base64 with encoding: "base64". For large binary content write base64 chunks with append. */
+        data: string;
+        /** Default "utf8". */
+        encoding?: Encoding;
+        url?: never;
+      }
+    | {
+        /**
+         * Copy the content of this URL: a FileRef of this session (camera.takePhoto, file-picker,
+         * readFile), or a blob:, data: or same-origin URL, which the page fetches first.
+         */
+        url: string;
+        data?: never;
+        encoding?: never;
+      }
+  );
+
+export interface FileInfo {
+  /** Symbolic links are followed by stat and reported as "symlink" by readDir. */
+  type: EntryType;
+  /** Bytes; 0 for folders. */
+  size: number;
+  /** Last modification, ms since the epoch (like Date.now()). 0 where unknown (OPFS folders). */
+  mtime: number;
+}
+
+export interface DirEntry extends FileInfo {
+  name: string;
+}
+
+export interface MoveOptions {
+  from: string;
+  to: string;
+  /** Base of `from`, and of `to` unless `toBase` is given. */
+  base: BaseDirectory;
+  toBase?: BaseDirectory;
+}
+
+export interface FilesystemApi {
+  readFile(options: PathOptions & { encoding: Encoding }): Promise<{ data: string }>;
+  readFile(options: PathOptions & { encoding?: undefined }): Promise<FileRef>;
+  readFile(options: ReadFileOptions): Promise<{ data: string } | FileRef>;
+  /** Creates or replaces the file (or appends to it). Parent folders must exist unless `recursive`. */
+  writeFile(options: WriteFileOptions): Promise<void>;
+  /** Entries of a folder ("" is the base itself), sorted by name. */
+  readDir(options: PathOptions): Promise<{ entries: DirEntry[] }>;
+  stat(options: PathOptions): Promise<FileInfo>;
+  exists(options: PathOptions): Promise<{ value: boolean }>;
+  /** Without `recursive` the parent must exist and the folder must not (INVALID_ARGS). */
+  mkdir(options: PathOptions & { recursive?: boolean }): Promise<void>;
+  /** Removes a file, a symbolic link (not its target) or a folder; non-empty folders need `recursive`. */
+  remove(options: PathOptions & { recursive?: boolean }): Promise<void>;
+  /**
+   * Moves a file or folder, also across bases (copy + remove where the bases are on different
+   * volumes). An existing file at `to` is replaced; an existing folder rejects INVALID_ARGS.
+   */
+  rename(options: MoveOptions): Promise<void>;
+  /** Copies a file, or a folder with everything in it. Same rules for `to` as rename. */
+  copy(options: MoveOptions): Promise<void>;
+  /** Absolute locations of the bases, for display and logs only; other methods take relative paths. */
+  paths(): Promise<Record<BaseDirectory, string>>;
+}
+
+const handle = definePlugin<FilesystemApi>("filesystem", {
+  methods: ["readFile", "writeFile", "readDir", "stat", "exists", "mkdir", "remove", "rename", "copy", "paths"],
+  web,
+});
+
+/**
+ * iOS and Android copy FileRefs of the session natively. Anything else given as `url` to a native
+ * host (a blob: URL from a web implementation, a data: URL, every URL on macOS, whose Bun host has
+ * no FileRef lookup) is fetched by the page and sent as base64.
+ */
+function inlinedByPage(url: unknown): url is string {
+  if (typeof url !== "string" || url.length === 0) return false;
+  return !((platform === "ios" || platform === "android") && fileRefId(url));
+}
+
+async function fetchAsBase64(url: string): Promise<string> {
+  let response: Response;
+  try {
+    response = await fetch(url);
+  } catch (error) {
+    throw new AkanNativeError("NOT_FOUND", `could not read ${url}`, { cause: error });
+  }
+  if (!response.ok) throw new AkanNativeError("NOT_FOUND", `could not read ${url} (${response.status})`);
+  return bytesToBase64(new Uint8Array(await response.arrayBuffer()));
+}
+
+/**
+ * The iOS bridge parses requests with JSONSerialization, which drops a U+FEFF (byte order mark) at
+ * the start of any string value (verified). Such text goes as base64 there, so the bytes on disk are
+ * the ones written everywhere.
+ */
+export function protectLeadingBom(options: WriteFileOptions): WriteFileOptions {
+  if (
+    platform !== "ios" ||
+    typeof options?.data !== "string" ||
+    (options.encoding ?? "utf8") !== "utf8" ||
+    !options.data.startsWith("\uFEFF")
+  ) {
+    return options;
+  }
+  return {
+    ...options,
+    data: bytesToBase64(new TextEncoder().encode(options.data)),
+    encoding: "base64",
+  } as WriteFileOptions;
+}
+
+export type Filesystem = Plugin<FilesystemApi>;
+
+export const filesystem: Filesystem = Object.freeze({
+  ...handle,
+  writeFile(options: WriteFileOptions): Promise<void> {
+    if (handle.implementation("writeFile") !== "native") return handle.writeFile(options);
+    if (!inlinedByPage(options?.url)) return handle.writeFile(protectLeadingBom(options));
+    const { url, ...rest } = options;
+    return fetchAsBase64(url!).then((data) =>
+      handle.writeFile({ ...rest, data, encoding: "base64" } as WriteFileOptions),
+    );
+  },
+});

package/vendor/@akanjs/native/plugins/filesystem/src/web.ts

@@ -0,0 +1,334 @@
+
+
+import {
+  AkanNativeError,
+  defineWebPlugin,
+  type FileRef,
+  type WebCallContext,
+} from "../../../packages/core/src/index.ts";
+import {
+  BASES,
+  base64ToBytes,
+  bytesToBase64,
+  checkBase,
+  checkEncoding,
+  checkFlag,
+  checkObject,
+  checkPath,
+  checkScope,
+  checkWriteSource,
+  decodeUtf8,
+  invalid,
+  mimeFor,
+  serialQueue,
+  sortEntries,
+} from "./common.ts";
+import type { BaseDirectory, DirEntry, FileInfo, FilesystemApi } from "./index.ts";
+
+interface FileHandle {
+  readonly kind: "file";
+  readonly name: string;
+  getFile(): Promise<File>;
+  createWritable?(options?: { keepExistingData?: boolean }): Promise<Writable>;
+}
+interface DirHandle {
+  readonly kind: "directory";
+  readonly name: string;
+  getFileHandle(name: string, options?: { create?: boolean }): Promise<FileHandle>;
+  getDirectoryHandle(name: string, options?: { create?: boolean }): Promise<DirHandle>;
+  removeEntry(name: string, options?: { recursive?: boolean }): Promise<void>;
+  entries(): AsyncIterable<[string, FileHandle | DirHandle]>;
+}
+interface Writable extends WritableStream<Uint8Array> {
+  write(data: Blob | BufferSource | string): Promise<void>;
+  seek(position: number): Promise<void>;
+  close(): Promise<void>;
+  abort(reason?: unknown): Promise<void>;
+}
+type Handle = FileHandle | DirHandle;
+
+const queue = serialQueue();
+
+function mapError(error: unknown): AkanNativeError {
+  if (error instanceof AkanNativeError) return error;
+  const name = (error as { name?: string })?.name;
+  const message = String((error as Error)?.message ?? error);
+  switch (name) {
+    case "NotFoundError":
+      return new AkanNativeError("NOT_FOUND", message || "not found");
+    case "TypeMismatchError": 
+    case "InvalidModificationError": // removing a non-empty folder without recursive
+      return new AkanNativeError("INVALID_ARGS", message);
+    case "NotAllowedError":
+    case "SecurityError":
+      return new AkanNativeError("PERMISSION_DENIED", message);
+    default:
+      return new AkanNativeError("INTERNAL", message);
+  }
+}
+
+/** Runs one operation in call order and maps DOMExceptions to AkanNativeError codes. */
+function op<T>(task: () => Promise<T>): Promise<T> {
+  return queue(task).catch((error: unknown) => {
+    throw mapError(error);
+  });
+}
+
+async function baseDir(base: BaseDirectory): Promise<DirHandle> {
+  const storage = globalThis.navigator?.storage as { getDirectory?: () => Promise<unknown> } | undefined;
+  if (typeof storage?.getDirectory !== "function") {
+    throw new AkanNativeError(
+      "UNSUPPORTED",
+      "the origin private file system is not available here (insecure context or old browser)",
+    );
+  }
+  const root = (await storage.getDirectory()) as DirHandle;
+  return root.getDirectoryHandle(base, { create: true });
+}
+
+async function dirAt(base: BaseDirectory, segments: string[], create = false): Promise<DirHandle> {
+  let dir = await baseDir(base);
+  for (const segment of segments) dir = await dir.getDirectoryHandle(segment, { create });
+  return dir;
+}
+
+/** The entry `name` in `parent`, or null. */
+async function lookup(parent: DirHandle, name: string): Promise<Handle | null> {
+  try {
+    return await parent.getFileHandle(name);
+  } catch (error) {
+    const kind = (error as { name?: string })?.name;
+    if (kind === "TypeMismatchError") return parent.getDirectoryHandle(name);
+    if (kind === "NotFoundError") return null;
+    throw error;
+  }
+}
+
+/** Parent folder and entry of a path (entry null when missing). The parent must exist. */
+async function locate(
+  base: BaseDirectory,
+  segments: string[],
+): Promise<{ parent: DirHandle; name: string; entry: Handle | null }> {
+  const parent = await dirAt(base, segments.slice(0, -1));
+  const name = segments.at(-1)!;
+  return { parent, name, entry: await lookup(parent, name) };
+}
+
+const notFound = (path: string) => new AkanNativeError("NOT_FOUND", `${path} does not exist`);
+
+async function info(handle: Handle): Promise<FileInfo> {
+  if (handle.kind === "directory") return { type: "directory", size: 0, mtime: 0 };
+  const file = await handle.getFile();
+  return { type: "file", size: file.size, mtime: file.lastModified };
+}
+
+async function isEmpty(dir: DirHandle): Promise<boolean> {
+  for await (const _ of dir.entries()) return false;
+  return true;
+}
+
+async function writable(handle: FileHandle, keepExistingData: boolean): Promise<Writable> {
+  if (typeof handle.createWritable !== "function") {
+    throw new AkanNativeError(
+      "UNSUPPORTED",
+      "this browser cannot write files from the page (FileSystemFileHandle.createWritable)",
+    );
+  }
+  return handle.createWritable({ keepExistingData });
+}
+
+async function copyInto(source: Handle, parent: DirHandle, name: string): Promise<void> {
+  if (source.kind === "file") {
+    const target = await parent.getFileHandle(name, { create: true });
+    const out = await writable(target, false);
+    await (await source.getFile()).stream().pipeTo(out); 
+    return;
+  }
+  const dir = await parent.getDirectoryHandle(name, { create: true });
+  for await (const [child, handle] of source.entries()) await copyInto(handle, dir, child);
+}
+
+async function move(args: unknown, keepSource: boolean, ctx?: WebCallContext): Promise<void> {
+  const o = checkObject(args);
+  const base = checkBase(o.base);
+  const toBase = o.toBase === undefined || o.toBase === null ? base : checkBase(o.toBase, "toBase");
+  const from = checkPath(o.from, false, "from");
+  const to = checkPath(o.to, false, "to");
+  checkScope(ctx?.scope, base, from);
+  checkScope(ctx?.scope, toBase, to);
+  if (base === toBase) {
+    if (from.join("/") === to.join("/")) throw invalid("from and to are the same path");
+    if (to.length > from.length && from.every((s, i) => to[i] === s))
+      throw invalid("cannot move or copy a folder into itself");
+  }
+  const src = await locate(base, from).catch((error) => {
+    throw (error as { name?: string })?.name === "NotFoundError" ? notFound(String(o.from)) : error;
+  });
+  if (!src.entry) throw notFound(String(o.from));
+  const dst = await locate(toBase, to);
+  if (dst.entry) {
+    if (dst.entry.kind === "directory") throw invalid(`${o.to} already exists and is a folder`);
+    if (src.entry.kind === "directory") throw invalid(`${o.to} already exists and is a file`);
+  }
+  await copyInto(src.entry, dst.parent, dst.name);
+  if (!keepSource) await src.parent.removeEntry(src.name, { recursive: true });
+}
+
+async function readFile(args: unknown, ctx?: WebCallContext): Promise<{ data: string } | FileRef> {
+  const o = checkObject(args);
+  const base = checkBase(o.base);
+  const segments = checkPath(o.path, false);
+  checkScope(ctx?.scope, base, segments);
+  const encoding = checkEncoding(o.encoding, true);
+  return op(async () => {
+    const { entry } = await locate(base, segments);
+    if (!entry) throw notFound(String(o.path));
+    if (entry.kind !== "file") throw invalid(`${o.path} is a folder`);
+    const file = await entry.getFile();
+    if (encoding === undefined) return { url: URL.createObjectURL(file), mime: mimeFor(entry.name), size: file.size };
+    const bytes = new Uint8Array(await file.arrayBuffer());
+    return { data: encoding === "utf8" ? decodeUtf8(bytes) : bytesToBase64(bytes) };
+  });
+}
+
+export const web = defineWebPlugin<FilesystemApi>({
+  methods: {
+    readFile: readFile as FilesystemApi["readFile"],
+
+    writeFile(args, ctx?: WebCallContext) {
+      const o = checkObject(args);
+      const base = checkBase(o.base);
+      const segments = checkPath(o.path, false);
+      checkScope(ctx?.scope, base, segments);
+      const source = checkWriteSource(o);
+      const append = checkFlag(o.append, "append");
+      const recursive = checkFlag(o.recursive, "recursive");
+      return op(async () => {
+        let content: Blob | Uint8Array | string;
+        if (source.kind === "url") {
+          const response = await fetch(source.url).catch((error: unknown) => {
+            throw new AkanNativeError("NOT_FOUND", `could not read ${source.url}`, { cause: error });
+          });
+          if (!response.ok) throw new AkanNativeError("NOT_FOUND", `could not read ${source.url} (${response.status})`);
+          content = await response.blob();
+        } else {
+          content = source.encoding === "base64" ? base64ToBytes(source.data) : source.data;
+        }
+        const parent = await dirAt(base, segments.slice(0, -1), recursive).catch((error) => {
+          throw (error as { name?: string })?.name === "NotFoundError" ? notFound(`the folder of ${o.path}`) : error;
+        });
+        const name = segments.at(-1)!;
+        const existing = await lookup(parent, name);
+        if (existing?.kind === "directory") throw invalid(`${o.path} is a folder`);
+        const handle = await parent.getFileHandle(name, { create: true });
+        const out = await writable(handle, append);
+        try {
+          if (append) await out.seek((await handle.getFile()).size);
+          await out.write(content as Blob | BufferSource | string);
+          await out.close();
+        } catch (error) {
+          await out.abort().catch(() => {});
+          throw error;
+        }
+      });
+    },
+
+    readDir(args, ctx?: WebCallContext) {
+      const o = checkObject(args);
+      const base = checkBase(o.base);
+      const segments = checkPath(o.path, true);
+      checkScope(ctx?.scope, base, segments);
+      return op(async () => {
+        const dir = await dirAt(base, segments).catch((error) => {
+          const kind = (error as { name?: string })?.name;
+          if (kind === "NotFoundError") throw notFound(String(o.path));
+          if (kind === "TypeMismatchError") throw invalid(`${o.path} is not a folder`);
+          throw error;
+        });
+        const entries: DirEntry[] = [];
+        for await (const [name, handle] of dir.entries()) entries.push({ name, ...(await info(handle)) });
+        return { entries: sortEntries(entries) };
+      });
+    },
+
+    stat(args, ctx?: WebCallContext) {
+      const o = checkObject(args);
+      const base = checkBase(o.base);
+      const segments = checkPath(o.path, true);
+      checkScope(ctx?.scope, base, segments);
+      return op(async () => {
+        if (segments.length === 0) return info(await baseDir(base));
+        const { entry } = await locate(base, segments).catch((error) => {
+          throw (error as { name?: string })?.name === "NotFoundError" ? notFound(String(o.path)) : error;
+        });
+        if (!entry) throw notFound(String(o.path));
+        return info(entry);
+      });
+    },
+
+    exists(args, ctx?: WebCallContext) {
+      const o = checkObject(args);
+      const base = checkBase(o.base);
+      const segments = checkPath(o.path, true);
+      checkScope(ctx?.scope, base, segments);
+      return op(async () => {
+        if (segments.length === 0) return { value: true };
+        try {
+          return { value: (await locate(base, segments)).entry !== null };
+        } catch (error) {
+          const kind = (error as { name?: string })?.name;
+          if (kind === "NotFoundError" || kind === "TypeMismatchError") return { value: false };
+          throw error;
+        }
+      });
+    },
+
+    mkdir(args, ctx?: WebCallContext) {
+      const o = checkObject(args);
+      const base = checkBase(o.base);
+      const segments = checkPath(o.path, true);
+      checkScope(ctx?.scope, base, segments);
+      const recursive = checkFlag(o.recursive, "recursive");
+      return op(async () => {
+        if (recursive) {
+          await dirAt(base, segments, true).catch((error) => {
+            throw (error as { name?: string })?.name === "TypeMismatchError"
+              ? invalid(`a file is in the way of ${o.path}`)
+              : error;
+          });
+          return;
+        }
+        if (segments.length === 0) throw invalid("the base folder already exists");
+        const { parent, name, entry } = await locate(base, segments).catch((error) => {
+          throw (error as { name?: string })?.name === "NotFoundError" ? notFound(`the folder of ${o.path}`) : error;
+        });
+        if (entry) throw invalid(`${o.path} already exists`);
+        await parent.getDirectoryHandle(name, { create: true });
+      });
+    },
+
+    remove(args, ctx?: WebCallContext) {
+      const o = checkObject(args);
+      const base = checkBase(o.base);
+      const segments = checkPath(o.path, false);
+      checkScope(ctx?.scope, base, segments);
+      const recursive = checkFlag(o.recursive, "recursive");
+      return op(async () => {
+        const { parent, name, entry } = await locate(base, segments).catch((error) => {
+          throw (error as { name?: string })?.name === "NotFoundError" ? notFound(String(o.path)) : error;
+        });
+        if (!entry) throw notFound(String(o.path));
+        if (entry.kind === "directory" && !recursive && !(await isEmpty(entry)))
+          throw invalid(`${o.path} is not empty (pass recursive: true)`);
+        await parent.removeEntry(name, { recursive });
+      });
+    },
+
+    rename: (args, ctx?: WebCallContext) => op(() => move(args, false, ctx)),
+    copy: (args, ctx?: WebCallContext) => op(() => move(args, true, ctx)),
+
+    async paths() {
+      return Object.fromEntries(BASES.map((base) => [base, `opfs:/${base}`])) as Record<BaseDirectory, string>;
+    },
+  },
+});