@symbiote-native/file-system 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A. Prokopenko
+
+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/README.md

@@ -0,0 +1,262 @@
+# @symbiote-native/file-system
+
+A wrapper package for [SymbioteNative](../../README.md) that makes
+[`expo-file-system`](https://github.com/expo/expo/tree/main/packages/expo-file-system) usable
+from **every** adapter — React, Vue, Svelte, Solid, and Angular.
+
+**Both of upstream's surfaces are ported, matching upstream's own layout.** The default export is
+the modern, shared-object API — `File`/`Directory`/`Paths` classes built on JSI shared objects
+(`expo-modules-core`'s `SharedObject`), upstream's own default entry as of SDK 54. The legacy,
+function-based API (read/write/copy/move/delete, directory listing, disk-space queries, resumable
+download/upload, Android Storage Access Framework) is available at the `./legacy` subpath,
+reachable in the real upstream package as `expo-file-system/legacy`. See
+[Legacy API (`/legacy`)](#legacy-api-legacy) below.
+
+## Install
+
+**New app:**
+
+```bash
+npx @symbiote-native/cli new my-app --file-system
+```
+
+**Existing SymbioteNative app:**
+
+```bash
+npx @symbiote-native/cli add --file-system
+```
+
+Either way: installs `@symbiote-native/file-system` and wires the native autolinking automatically — see
+[`@symbiote-native/cli`](../cli).
+
+<details>
+<summary>Manual install (no CLI — installing and wiring native autolinking by hand)</summary>
+
+```bash
+npm install @symbiote-native/file-system
+```
+
+`expo-file-system` and `expo-modules-core` come along as regular dependencies, pinned to exact
+versions — never install them yourself, and never add the `expo` meta-package to your project.
+
+## Required one-time step: native autolinking wiring
+
+Same one-time step as every other `expo-modules-core` package this project ships — see
+[`@symbiote-native/local-auth`'s README](../local-auth/README.md#required-one-time-step-native-autolinking-wiring)
+and the `symbiote-expo-native-module` project skill.
+
+`native-link.json` carries no `Info.plist` keys or `<application>` attributes — upstream's own
+config plugin only sets two OPT-IN keys (`LSSupportsOpeningDocumentsInPlace`,
+`UIFileSharingEnabled`), which an app adds itself only if it wants its Documents directory exposed
+to the Files app; nothing here needs either by default.
+
+</details>
+
+**Android runtime permissions are NOT added automatically, by the CLI or otherwise** — add
+whichever of these your app actually needs to your own `AndroidManifest.xml`, the same opt-in
+shape [`@symbiote-native/media-library`](../media-library) uses:
+
+```xml
+<uses-permission android:name="android.permission.INTERNET" />
+<!-- only if reading/writing outside your app's own sandboxed directories -->
+<uses-permission android:name="android.permission.READ_EXTERNAL_STORAGE" />
+<uses-permission android:name="android.permission.WRITE_EXTERNAL_STORAGE" />
+```
+
+`Paths.document`/`Paths.cache` operations and `StorageAccessFramework` (which asks the user to pick
+a directory at runtime, and never touches the two `EXTERNAL_STORAGE` permissions) both work without
+any of these on modern Android — they matter only for direct legacy-path access outside the app
+sandbox.
+
+## Shape
+
+```
+src/next/     File.ts / Directory.ts / Paths.ts / network-tasks.ts (UploadTask/DownloadTask) /
+              watcher.ts (FileSystemWatcher) / path-utilities.ts / streams.ts / types.ts —
+              the default, shared-object surface. See "API" below.
+src/core/     file-system.ts (every legacy function + DownloadResumable/UploadTask +
+              StorageAccessFramework), native-module.ts, types.ts. See "Legacy API" below.
+src/angular/  @symbiote-native/file-system/angular — export * from '../next'
+```
+
+`./react`, `./vue`, `./svelte`, and `./solid` are `exports`-map aliases straight onto `src/next/`
+— every class here carries no children/ref/render fields, so there is nothing to split per
+framework. `./angular` stays a physical file/subpath since Angular ships through a separate
+`ngc`/AOT build (`build-ngc/`). `./legacy` is one subpath shared by every adapter, for the same
+reason — plain async functions have no framework-specific shape either.
+
+## Use it
+
+```ts
+import { File, Directory, Paths } from '@symbiote-native/file-system';
+
+const file = new File(Paths.document, 'notes.txt');
+file.write('hello world');
+const contents = file.text();
+
+const dir = new Directory(Paths.document, 'photos');
+dir.create();
+const entries = dir.list();
+
+const downloaded = await File.downloadFileAsync(
+  'https://example.com/big-file.zip',
+  Paths.cache,
+  {
+    onProgress: ({ bytesWritten, totalBytes }) =>
+      console.log(bytesWritten / totalBytes),
+  },
+);
+```
+
+Identical import surface on every adapter — `@symbiote-native/file-system/react`, `/vue`,
+`/svelte`, `/solid`, `/angular` all re-export the same classes.
+
+## API
+
+### `File`
+
+```ts
+new File(...uris: (string | File | Directory)[])
+static downloadFileAsync(url, destination, options?): Promise<File>
+static pickFileAsync(options?): Promise<IPickSingleFileResult | IPickMultipleFilesResult>
+static createDownloadTask(url, destination, options?): DownloadTask
+
+.uri / .exists / .size / .md5 / .type / .lastModified / .creationTime / .parentDirectory /
+.extension / .name
+.write(contents, options?) / .text() / .bytes() / .base64()          // + Sync variants
+.create(options?) / .delete() / .copy(dest) / .move(dest)            // + Sync variants
+.open(mode) -> IFileSystemHandle
+.readableStream() / .writableStream() / .stream() / .arrayBuffer() / .json() / .formData()
+.slice(start?, end?, contentType?): Blob
+.upload(url, options?): Promise<IFileSystemUploadResult>
+.createUploadTask(url, options?): UploadTask
+.watch(callback, options?): IFileSystemWatchSubscription
+```
+
+### `Directory`
+
+```ts
+new Directory(...uris: (string | File | Directory)[])
+static pickDirectoryAsync(initialUri?): Promise<Directory>
+
+.uri / .exists / .size / .parentDirectory / .name
+.create(options?) / .delete() / .copy(dest) / .move(dest)
+.list(): (File | Directory)[]
+.createFile(name, options?): File
+.createDirectory(name, options?): Directory
+.watch(callback, options?): IFileSystemWatchSubscription
+```
+
+### `Paths`
+
+```ts
+Paths.cache / Paths.document / Paths.bundle: Directory
+Paths.appleSharedContainers: Record<string, Directory>              // ios only
+Paths.totalDiskSpace / Paths.availableDiskSpace: number
+Paths.info(...uris): IPathInfo
+Paths.join / .relative / .isAbsolute / .normalize / .dirname / .basename / .extname / .parse
+```
+
+### `UploadTask` / `DownloadTask`
+
+State machines over a network transfer, both cancellable via `AbortSignal`:
+
+```ts
+new UploadTask(file, url, options?)
+.uploadAsync(): Promise<IFileSystemUploadResult>
+.state: IFileSystemUploadTaskState                                  // idle/active/completed/cancelled/error
+
+new DownloadTask(url, destination, options?)
+.downloadAsync(): Promise<File>
+.pause() / .resume()
+.savable(): IFileSystemDownloadPauseState                            // resume after app restart
+static fromSavable(savable): DownloadTask
+.state: IFileSystemDownloadTaskState                                 // + paused
+```
+
+### Errors
+
+No custom JS error-class hierarchy — every native exception surfaces as an ordinary thrown `Error`
+or rejected `Promise`, same as every other native module wrapper in this repo.
+
+| Trigger                                                                             | When                                                                                                       |
+| ----------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
+| Constructing a `File`/`Directory` with an invalid/empty path                        | `validatePath()` throws synchronously in the constructor                                                   |
+| Reading/writing through a stale or already-closed handle                            | `IFileSystemHandle` methods throw                                                                          |
+| `pickFileAsync`/`pickDirectoryAsync` cancelled by the user                          | Rejects with an `AbortError` (old-API overload) or resolves `{ canceled: true }` (options-object overload) |
+| `upload()`/`createUploadTask()`/`createDownloadTask()` aborted via `options.signal` | Rejects with an `AbortError`                                                                               |
+| `.copy()`/`.move()` onto an existing destination without `overwrite: true`          | Native `Exception` — destination already exists                                                            |
+| Any operation on a path outside the app sandbox without permission                  | Native `Exception` — permission/sandbox violation                                                          |
+
+## Legacy API (`/legacy`)
+
+Upstream's original function-based surface — plain async functions over `expo-modules-core`
+instead of JSI shared objects. Same install, same autolinking step as above; the native module
+behind it is a **separate** registration (`ExponentFileSystem`, vs. the modern API's
+`FileSystem`) inside the same `expo-file-system` npm dependency — nothing extra to install.
+
+```ts
+import {
+  documentDirectory,
+  writeAsStringAsync,
+  readAsStringAsync,
+  downloadAsync,
+  createDownloadResumable,
+} from '@symbiote-native/file-system/legacy';
+
+const fileUri = `${documentDirectory}notes.txt`;
+await writeAsStringAsync(fileUri, 'hello world');
+const contents = await readAsStringAsync(fileUri);
+
+const resumable = createDownloadResumable(
+  'https://example.com/big-file.zip',
+  `${documentDirectory}big-file.zip`,
+  undefined,
+  ({ totalBytesWritten, totalBytesExpectedToWrite }) => {
+    console.log(totalBytesWritten / totalBytesExpectedToWrite);
+  },
+);
+await resumable.downloadAsync();
+```
+
+### Legacy API reference
+
+```ts
+documentDirectory / cacheDirectory / bundleDirectory: string | null       // trailing-slash-normalized
+getInfoAsync(fileUri, options?): Promise<IFileSystemFileInfo>
+readAsStringAsync(fileUri, options?): Promise<string>
+writeAsStringAsync(fileUri, contents, options?): Promise<void>
+getContentUriAsync(fileUri): Promise<string>                              // android; echoes input on ios
+deleteAsync(fileUri, options?): Promise<void>
+moveAsync(options) / copyAsync(options): Promise<void>                    // { from, to }
+makeDirectoryAsync(fileUri, options?): Promise<void>
+readDirectoryAsync(fileUri): Promise<string[]>
+getFreeDiskStorageAsync() / getTotalDiskCapacityAsync(): Promise<number>  // bytes
+downloadAsync(uri, fileUri, options?): Promise<IFileSystemDownloadResult>
+uploadAsync(url, fileUri, options?): Promise<IFileSystemUploadResult>
+createDownloadResumable(uri, fileUri, options?, callback?, resumeData?): DownloadResumable
+createUploadTask(url, fileUri, options?, callback?): UploadTask
+StorageAccessFramework.{ getUriForDirectoryInRoot, requestDirectoryPermissionsAsync,
+  readDirectoryAsync, makeDirectoryAsync, createFileAsync,
+  writeAsStringAsync, readAsStringAsync, deleteAsync, moveAsync, copyAsync }  // android
+FileSystemSessionType, FileSystemUploadType, FileSystemEncodingType        // runtime enums
+```
+
+`DownloadResumable` carries `cancelAsync`/`pauseAsync`/`resumeAsync`/`savable()`;
+`UploadTask` carries `cancelAsync`/`uploadAsync`. Both report progress through the `callback`
+passed at construction, driven by a native event subscription keyed on the task's own uuid.
+
+Plus every `IFileSystem*` type, ported from upstream's `legacy/FileSystem.types.ts` with this
+repo's `I`-prefix convention for exported types (`ts-js-best-practices`).
+
+### Legacy notes
+
+- **`StorageAccessFramework` is Android-only** — every function throws `UnavailabilityError` on iOS,
+  matching upstream (there is no SAF equivalent on iOS; use the ordinary `document`/`cacheDirectory`
+  functions there instead).
+- **`getContentUriAsync` is Android-only** — on iOS it resolves to the input `fileUri` unchanged,
+  matching upstream's own platform branch, rather than throwing.
+- **Progress callbacks fire only while a task is subscribed** — `DownloadResumable`/`UploadTask`
+  add their native event listener only for the duration of the in-flight call
+  (`downloadAsync`/`uploadAsync`/`resumeAsync`), removing it as soon as the promise settles, exactly
+  as upstream does.

package/build/angular/index.d.ts

@@ -0,0 +1 @@
+export * from '../next';

package/build/angular/index.js

@@ -0,0 +1 @@
+export * from '../next/index.js';

package/build/core/file-system.d.ts

@@ -0,0 +1,169 @@
+import { type IFileSystemDeletingOptions, type IFileSystemDownloadOptions, type IFileSystemDownloadPauseState, type IFileSystemDownloadProgressData, type IFileSystemDownloadResult, type IFileSystemFileInfo, type IFileSystemInfoOptions, type IFileSystemMakeDirectoryOptions, type IFileSystemNetworkTaskProgressCallback, type IFileSystemReadingOptions, type IFileSystemRelocatingOptions, type IFileSystemRequestDirectoryPermissionsResult, type IFileSystemUploadOptions, type IFileSystemUploadProgressData, type IFileSystemUploadResult, type IFileSystemWritingOptions } from './types';
+/**
+ * `file://` URI pointing to the directory where user documents for this app will be stored.
+ * Files stored here will remain until explicitly deleted by the app. Ends with a trailing `/`.
+ */
+export declare const documentDirectory: string | null;
+/**
+ * `file://` URI pointing to the directory where temporary files used by this app will be stored.
+ * Files stored here may be automatically deleted by the system when low on storage.
+ */
+export declare const cacheDirectory: string | null;
+/**
+ * URI to the directory where assets bundled with the application are stored.
+ */
+export declare const bundleDirectory: string | null;
+/**
+ * Get metadata information about a file, directory or external content/asset.
+ */
+export declare function getInfoAsync(fileUri: string, options?: IFileSystemInfoOptions): Promise<IFileSystemFileInfo>;
+/**
+ * Read the entire contents of a file as a string. Binary is returned in raw format — prepend
+ * `data:image/png;base64,` yourself to use it as a data URI.
+ */
+export declare function readAsStringAsync(fileUri: string, options?: IFileSystemReadingOptions): Promise<string>;
+/**
+ * Takes a `file://` URI and converts it into a `content://` URI so that it can be accessed by
+ * other applications outside of the app.
+ * @platform android
+ */
+export declare function getContentUriAsync(fileUri: string): Promise<string>;
+/**
+ * Write the entire contents of a file as a string.
+ */
+export declare function writeAsStringAsync(fileUri: string, contents: string, options?: IFileSystemWritingOptions): Promise<void>;
+/**
+ * Delete a file or directory. If the URI points to a directory, the directory and all its
+ * contents are recursively deleted.
+ */
+export declare function deleteAsync(fileUri: string, options?: IFileSystemDeletingOptions): Promise<void>;
+/**
+ * Move a file or directory to a new location.
+ */
+export declare function moveAsync(options: IFileSystemRelocatingOptions): Promise<void>;
+/**
+ * Create a copy of a file or directory. Directories are recursively copied with all of their
+ * contents. Also works to copy content shared by other apps into local storage.
+ */
+export declare function copyAsync(options: IFileSystemRelocatingOptions): Promise<void>;
+/**
+ * Create a new empty directory.
+ */
+export declare function makeDirectoryAsync(fileUri: string, options?: IFileSystemMakeDirectoryOptions): Promise<void>;
+/**
+ * Enumerate the contents of a directory.
+ */
+export declare function readDirectoryAsync(fileUri: string): Promise<string[]>;
+/**
+ * Gets the available internal disk storage size, in bytes.
+ */
+export declare function getFreeDiskStorageAsync(): Promise<number>;
+/**
+ * Gets total internal disk storage size, in bytes.
+ */
+export declare function getTotalDiskCapacityAsync(): Promise<number>;
+/**
+ * Download the contents at a remote URI to a file in the app's file system. The directory for
+ * the local file URI must exist prior to calling this function.
+ */
+export declare function downloadAsync(uri: string, fileUri: string, options?: IFileSystemDownloadOptions): Promise<IFileSystemDownloadResult>;
+/**
+ * Upload the contents of the file pointed by `fileUri` to the remote url.
+ */
+export declare function uploadAsync(url: string, fileUri: string, options?: IFileSystemUploadOptions): Promise<IFileSystemUploadResult>;
+/**
+ * Create a `DownloadResumable` object which can start, pause, and resume a download of contents
+ * at a remote URI to a file in the app's file system.
+ */
+export declare function createDownloadResumable(uri: string, fileUri: string, options?: IFileSystemDownloadOptions, callback?: IFileSystemNetworkTaskProgressCallback<IFileSystemDownloadProgressData>, resumeData?: string): DownloadResumable;
+export declare function createUploadTask(url: string, fileUri: string, options?: IFileSystemUploadOptions, callback?: IFileSystemNetworkTaskProgressCallback<IFileSystemUploadProgressData>): UploadTask;
+export declare abstract class FileSystemCancellableNetworkTask<T extends IFileSystemDownloadProgressData | IFileSystemUploadProgressData> {
+    private _uuid;
+    protected taskWasCanceled: boolean;
+    private subscription?;
+    cancelAsync(): Promise<void>;
+    protected isTaskCancelled(): boolean;
+    protected get uuid(): string;
+    protected abstract getEventName(): string;
+    protected abstract getCallback(): IFileSystemNetworkTaskProgressCallback<T> | undefined;
+    protected addSubscription(): void;
+    protected removeSubscription(): void;
+}
+export declare class UploadTask extends FileSystemCancellableNetworkTask<IFileSystemUploadProgressData> {
+    private url;
+    private fileUri;
+    private callback?;
+    private options;
+    constructor(url: string, fileUri: string, options?: IFileSystemUploadOptions, callback?: IFileSystemNetworkTaskProgressCallback<IFileSystemUploadProgressData> | undefined);
+    protected getEventName(): string;
+    protected getCallback(): IFileSystemNetworkTaskProgressCallback<IFileSystemUploadProgressData> | undefined;
+    uploadAsync(): Promise<IFileSystemUploadResult | undefined | null>;
+}
+export declare class DownloadResumable extends FileSystemCancellableNetworkTask<IFileSystemDownloadProgressData> {
+    private url;
+    private _fileUri;
+    private options;
+    private callback?;
+    private resumeData?;
+    constructor(url: string, _fileUri: string, options?: IFileSystemDownloadOptions, callback?: IFileSystemNetworkTaskProgressCallback<IFileSystemDownloadProgressData> | undefined, resumeData?: string | undefined);
+    get fileUri(): string;
+    protected getEventName(): string;
+    protected getCallback(): IFileSystemNetworkTaskProgressCallback<IFileSystemDownloadProgressData> | undefined;
+    /**
+     * Download the contents at a remote URI to a file in the app's file system.
+     */
+    downloadAsync(): Promise<IFileSystemDownloadResult | undefined>;
+    /**
+     * Pause the current download operation. `resumeData` is added to the `DownloadResumable`
+     * object after a successful pause operation. Returns an object that can be persisted
+     * (e.g. via a storage module) for future retrieval.
+     */
+    pauseAsync(): Promise<IFileSystemDownloadPauseState>;
+    /**
+     * Resume a paused download operation.
+     */
+    resumeAsync(): Promise<IFileSystemDownloadResult | undefined>;
+    /**
+     * The object which can be persisted for future retrieval (e.g. via a storage module), and
+     * fed back into `createDownloadResumable` after an app restart.
+     */
+    savable(): IFileSystemDownloadPauseState;
+}
+/**
+ * `StorageAccessFramework` encapsulates the functions usable with SAF URIs, for accessing
+ * user-selected directories outside the app's own storage.
+ * @platform android
+ */
+export declare const StorageAccessFramework: {
+    /**
+     * Gets a SAF URI pointing to a folder in the Android root directory, given the folder name.
+     * @platform android
+     */
+    getUriForDirectoryInRoot(folderName: string): string;
+    /**
+     * Allows users to select a specific directory, granting the app access to all of the files and
+     * sub-directories within it.
+     * @platform android 11+
+     */
+    requestDirectoryPermissionsAsync(initialFileUrl?: string | null): Promise<IFileSystemRequestDirectoryPermissionsResult>;
+    /**
+     * Enumerate the contents of a directory addressed by a SAF URI.
+     * @platform android
+     */
+    readDirectoryAsync(dirUri: string): Promise<string[]>;
+    /**
+     * Creates a new empty directory addressed by a SAF URI.
+     * @platform android
+     */
+    makeDirectoryAsync(parentUri: string, dirName: string): Promise<string>;
+    /**
+     * Creates a new empty file addressed by a SAF URI.
+     * @platform android
+     */
+    createFileAsync(parentUri: string, fileName: string, mimeType: string): Promise<string>;
+    writeAsStringAsync: typeof writeAsStringAsync;
+    readAsStringAsync: typeof readAsStringAsync;
+    deleteAsync: typeof deleteAsync;
+    moveAsync: typeof moveAsync;
+    copyAsync: typeof copyAsync;
+};