@vrcalphabet/web-fs 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 vrcalpha
+
+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,131 @@
+# web-fs
+
+[![npm version](https://badge.fury.io/js/@vrcalphabet/web-fs.svg)](https://badge.fury.io/js/@vrcalphabet/web-fs)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue.svg)](https://www.typescriptlang.org/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+TypeScriptで書かれたFile System APIを簡単に操作するためのラッパーライブラリです。
+
+## 例
+
+### テキストファイルの読み込み
+
+```typescript
+import { pickFile } from "@vrcalphabet/web-fs";
+
+const handle = await pickFile({
+  types: [
+    {
+      description: "テキストファイル",
+      accept: [".txt"],
+    },
+  ],
+});
+
+if (handle) {
+  const content = await handle.text();
+  console.log(content);
+}
+```
+
+### ディレクトリ構造の表示
+
+```typescript
+import { pickDirectory } from "@vrcalphabet/web-fs";
+
+const dirHandle = await pickDirectory();
+
+if (dirHandle) {
+  const tree = await dirHandle.treeString();
+  console.log(tree);
+}
+```
+
+### ファイルの作成と書き込み
+
+```typescript
+import { pickDirectory } from "@vrcalphabet/web-fs";
+
+const dirHandle = await pickDirectory({ mode: "readwrite" });
+
+if (dirHandle) {
+  const fileHandle = await dirHandle.createFile("example.txt");
+  if (fileHandle) {
+    await fileHandle.write("Hello, World!");
+  }
+}
+```
+
+### Globパターンによる検索
+
+```typescript
+import { pickDirectory } from "@vrcalphabet/web-fs";
+
+const dirHandle = await pickDirectory();
+
+if (dirHandle) {
+  // srcディレクトリ以下のすべてのtsファイルを取得
+  const files = await dirHandle.glob("src/**/*.ts");
+  for (const file of files) {
+    console.log((await file.info()).name);
+  }
+}
+```
+
+### ハンドルの永続化
+
+```typescript
+import { pickFile } from "@vrcalphabet/web-fs";
+
+// IDを指定して永続化を有効にする
+const handle = await pickFile({
+  id: "my-text-file",
+  persistence: true,
+});
+
+if (handle) {
+  // 次回以降、同じIDを指定するとピッカーを表示せずにハンドルを取得可能
+  console.log(await handle.text());
+}
+```
+
+## インストール
+
+### npm
+
+```bash
+npm install @vrcalphabet/web-fs
+```
+
+### yarn
+
+```bash
+yarn add @vrcalphabet/web-fs
+```
+
+### pnpm
+
+```bash
+pnpm add @vrcalphabet/web-fs
+```
+
+## 貢献
+
+プロジェクトへの貢献を歓迎します！以下のルールに従うと，あなたの貢献がスムーズになります！
+
+### Issue / PR
+
+Issueを立てる際は，バグ報告・機能要望のどちらかを明記してください。
+PRの説明には，目的・変更点・影響範囲・サンプルコードがあるとありがたいです。
+
+## ライセンス
+
+MIT License
+
+詳細は[LICENSE](./LICENSE)ファイルを参照してください。
+
+## 変更履歴・リリース情報
+
+### v1.0.0 (2026-02-02)
+
+- 初回リリース

package/dist/main.d.ts

@@ -0,0 +1,387 @@
+/**
+ * ディレクトリを`WebFsDirectoryHandle`でラップしたものを返します。
+ *
+ * @param directoryHandle すでに取得しているディレクトリハンドル。
+ * @param options ディレクトリのオプション。
+ * @returns 成功した場合は`WebFsDirectoryHandle`、エラーが出た場合は`undefined`。
+ */
+export declare function mountDirectory(directoryHandle: FileSystemDirectoryHandle, options?: WebFsPermissionOptions): Promise<WebFsDirectoryHandle | undefined>;
+
+/**
+ * ファイルを`WebFsFileHandle`でラップしたものを返します。
+ *
+ * @param fileHandle すでに取得しているファイルハンドル。
+ * @param options ファイルのオプション。
+ * @returns 成功した場合は`WebFsFileHandle`、エラーが出た場合は`undefined`。
+ */
+export declare function mountFile(fileHandle: FileSystemFileHandle, options?: WebFsPermissionOptions): Promise<WebFsFileHandle | undefined>;
+
+/**
+ * ユーザに単一のディレクトリを選択させ、そのディレクトリを`WebFsDirectoryHandle`でラップしたものを返します。
+ *
+ * @param options ディレクトリ選択のオプション。
+ * @returns 成功した場合は`WebFsDirectoryHandle`、選択を取り消した場合やエラーが出た場合は`undefined`。
+ */
+export declare function pickDirectory(options?: WebFsDirectoryPickOptions): Promise<WebFsDirectoryHandle | undefined>;
+
+/**
+ * ユーザに単一のファイルを選択させ、そのファイルを`WebFsFileHandle`でラップしたものを返します。
+ *
+ * @param options ファイル選択のオプション。
+ * @returns 成功した場合は`WebFsFileHandle`、選択を取り消した場合やエラーが出た場合は`undefined`。
+ */
+export declare function pickFile(options?: WebFsFilePickOptions): Promise<WebFsFileHandle | undefined>;
+
+/**
+ * ユーザに複数のファイルを選択させ、そのファイルリストを`WebFsFileHandleList`でラップしたものを返します。
+ *
+ * @param options ファイル選択のオプション。
+ * @returns 成功した場合は`WebFsFileHandleList`、選択を取り消した場合やエラーが出た場合は`undefined`。
+ */
+export declare function pickFiles(options?: WebFsFilePickOptions): Promise<WebFsFileHandleList | undefined>;
+
+/**
+ * ブラウザが`web-fs`に対応しているかを確認します。\
+ * 値として`false`が返った場合は、その他の関数や`WebFs*`クラスを使用できません。
+ *
+ * @returns 対応している場合は`true`、そうでない場合は`false`。
+ */
+export declare function supportsWebFs(): boolean;
+
+/**
+ * 保存されたディレクトリハンドルを削除します。
+ *
+ * @param id 削除したいディレクトリハンドルのid。
+ */
+export declare function unmountDirectory(id: string): Promise<void>;
+
+/**
+ * 保存されたファイルハンドルを削除します。
+ *
+ * @param id 削除したいファイルハンドルのid。
+ */
+export declare function unmountFile(id: string): Promise<void>;
+
+export declare class WebFsDirectoryHandle extends WebFsHandle {
+    /**
+     * ディレクトリハンドルの種類。常に`"directory"`を返します。
+     */
+    readonly type = "directory";
+    protected _handle: FileSystemDirectoryHandle;
+    private constructor();
+    /**
+     * ファイルを`WebFsFileHandle`でラップしたものを返します。
+     *
+     * @param handle すでに取得しているファイルハンドル。
+     * @param mode ファイルのオプション。
+     * @returns 成功した場合は`WebFsFileHandle`、エラーが出た場合は`undefined`。
+     */
+    static create(handle: FileSystemDirectoryHandle, mode?: FileSystemPermissionMode): Promise<WebFsDirectoryHandle | undefined>;
+    /**
+     * ファイルを取得します。ファイル名またはファイルの相対パスを指定します。
+     *
+     * @param filePath 取得するファイルのファイルパス。
+     * @param options ファイルのオプション。
+     * @returns ファイルが取得できた場合は`WebFsFileHandle`、`options.create`が`false`かつファイルが存在しない場合、またはエラーが出た場合は`undefined`。
+     */
+    file(filePath: string, options?: WebFsGetFileOptions): Promise<WebFsFileHandle | undefined>;
+    /**
+     * ディレクトリを取得します。ディレクトリ名またはディレクトリの相対パスで指定します。
+     *
+     * @param dirPath 取得するディレクトリのファイルパス。
+     * @param options ディレクトリのオプション。
+     * @returns ディレクトリが取得できた場合は`WebFsDirectoryHandle`、`options.create`が`false`かつディレクトリが存在しない場合、またはエラーが出た場合は`undefined`。
+     */
+    dir(dirPath: string, options?: WebFsGetDirectoryOptions): Promise<WebFsDirectoryHandle | undefined>;
+    /**
+     * ファイルを簡易的なglobパターンから取得します。
+     *
+     * @returns globパターンにマッチしたファイルの`WebFsFileHandle`の配列。
+     */
+    glob(pattern: string): Promise<WebFsFileHandle[]>;
+    private _glob;
+    /**
+     * ファイルを作成します。ファイル名またはファイルの相対パスで指定します。
+     *
+     * @returns ファイルが作成できた場合はそのファイルの`WebFsFileHandle`、エラーが出た場合は`undefined`。
+     */
+    createFile(filePath: string, options?: WebFsPermissionOptions): Promise<WebFsFileHandle | undefined>;
+    /**
+     * ディレクトリを作成します。ディレクトリ名またはディレクトリの相対パスで指定します。
+     *
+     * @returns ディレクトリが作成できた場合はそのディレクトリの`WebFsDirectoryHandle`、エラーが出た場合は`undefined`。
+     */
+    createDir(dirPath: string, options?: WebFsPermissionOptions): Promise<WebFsDirectoryHandle | undefined>;
+    /**
+     * ファイルまたはディレクトリを削除します。削除するエントリーがディレクトリであった場合は、その子孫を再帰的に削除します。
+     *
+     * @param entryPath 削除するファイルまたはディレクトリの名前。
+     * @returns 削除に成功した場合は`true`、エントリーが存在しないまたはエラーの場合は`false`。
+     */
+    remove(entryPath: string): Promise<boolean>;
+    /**
+     * 現在の階層にあるファイル名またはディレクトリ名の一覧を取得します。
+     *
+     * @param [options={}] 一覧のオプション。
+     * @returns ファイル名またはディレクトリ名からなる配列を返します。
+     */
+    names({ file, dir, depth, }?: WebFsEntryListOptions): Promise<string[]>;
+    /**
+     * 現在の階層にあるファイルまたはディレクトリのハンドルの一覧を取得します。
+     *
+     * @param [options={}] 一覧のオプション。
+     * @returns ファイルハンドルまたはディレクトリハンドルからなる配列を返します。
+     */
+    list({ file, dir, depth, }?: WebFsEntryListOptions): Promise<(WebFsFileHandle | WebFsDirectoryHandle)[]>;
+    /**
+     * ファイル構造をツリー形式として取得します。
+     *
+     * @returns ツリー形式のオブジェクト。
+     */
+    tree({ file, dir, depth, }?: WebFsEntryListOptions): Promise<WebFsTreeResult>;
+    /**
+     * ファイル構造を文字列のツリー形式として取得します。
+     *
+     * 返り値の例：
+     * ```text
+     * babel/
+     *  ├─ code-frame/
+     *  │  ├─ lib/
+     *  │  ├─ LICENSE
+     *  │  ├─ package.json
+     *  │  └─ README.md
+     *  ├─ compat-data/
+     *  │  ├─ data/
+     *  │  ├─ corejs3-shipped-proposals.js
+     *  │  ├─ plugin-bugfixes.js
+     *  │  ├─ corejs2-built-ins.js
+     *  ...
+     * ```
+     *
+     * @returns ツリー形式の文字列。
+     */
+    treeString({ file, dir, depth, }?: WebFsEntryListOptions): Promise<string>;
+    private _tree;
+    private _flat;
+    private _toString;
+    private _filterEntry;
+    private _dirByPath;
+}
+
+/** ディレクトリを選択する際のオプションです。 */
+export declare type WebFsDirectoryPickOptions = WebFsPickOptions & {};
+
+/** エントリーリストを取得する際のオプションです。 */
+export declare interface WebFsEntryListOptions {
+    /** 要素にファイルハンドルを含めるかを指定します。デフォルトは`true`です。 */
+    file?: boolean;
+    /** 要素にディレクトリハンドルを含めるかを指定します。デフォルトは`true`です。 */
+    dir?: boolean;
+    /** 再帰する深さを指定します。デフォルトは`1`です。 */
+    depth?: number;
+}
+
+export declare class WebFsFileHandle extends WebFsHandle {
+    /**
+     * ファイルハンドルの種類。常に`"file"`を返します。
+     */
+    readonly type = "file";
+    protected _handle: FileSystemFileHandle;
+    private constructor();
+    /**
+     * ファイルを`WebFsFileHandle`でラップしたものを返します。
+     *
+     * @param handle すでに取得しているファイルハンドル。
+     * @param mode ファイルのオプション。
+     * @returns 成功した場合は`WebFsFileHandle`、エラーが出た場合は`undefined`。
+     */
+    static create(handle: FileSystemFileHandle, mode?: FileSystemPermissionMode): Promise<WebFsFileHandle | undefined>;
+    /**
+     * ファイルの情報を返します。\
+     * これには、ファイル名、ファイルサイズ、MIMEの種類、パス、最終更新日時が含まれます。
+     *
+     * @returns ファイルの情報。
+     */
+    info(): Promise<WebFsFileInfo>;
+    /**
+     * ファイルの内容をUTF-8形式の文字列として取得します。
+     *
+     * @returns ファイルの内容を解釈した文字列を返します。
+     */
+    text(): Promise<string>;
+    /**
+     * ファイルの内容をUTF-8形式のJSONと解釈したうえで、オブジェクトに変換して返します。
+     *
+     * @returns 有効なJSON構文である場合は`unknown`、そうでない場合は`undefined`が返ります。
+     */
+    json<T = unknown>(): Promise<T | undefined>;
+    /**
+     * ファイルを`Blob`として取得します。
+     *
+     * @returns ファイルの`Blob`オブジェクト。
+     */
+    blob(): Promise<Blob>;
+    /**
+     * ファイルを`arrayBuffer`として取得します。
+     *
+     * @returns ファイルの`arrayBuffer`オブジェクト。
+     */
+    arrayBuffer(): Promise<ArrayBuffer>;
+    /**
+     * ファイルのハッシュ値を取得します。\
+     * ハッシュ値のアルゴリズムは、`md5`、`sha256`、`sha512`から選べます。
+     *
+     * @returns ハッシュ化された16進数の文字列。
+     */
+    hash(algo?: WebFsFileHashType): Promise<string>;
+    /**
+     * ファイルの内容を`data`の内容で**上書き**します。
+     *
+     * @returns ファイルの書き込みに成功した場合は`true`、失敗した場合は`false`。
+     */
+    write(data: string): Promise<boolean>;
+    /**
+     * ファイルの内容に`data`の内容を追記します。
+     *
+     * @returns ファイルの書き込みに成功した場合は`true`、失敗した場合は`false`。
+     */
+    append(data: string): Promise<boolean>;
+    /**
+     * ファイルの読み込みストリームを取得します。
+     *
+     * @returns ファイルの読み込みストリーム。
+     */
+    readStream(): Promise<ReturnType<Blob["stream"]>>;
+    /**
+     * ファイルの書き込みストリームを取得します。
+     *
+     * @returns ファイルの書き込みストリーム。
+     */
+    writeStream(options?: FileSystemCreateWritableOptions): Promise<FileSystemWritableFileStream>;
+    private _write;
+}
+
+declare class WebFsFileHandleList {
+    private _handles;
+    private constructor();
+    /**
+     * ファイルを`WebFsFileHandleList`（`WebFsFileHandle`の配列）でラップしたものを返します。
+     *
+     * @param handles すでに取得しているファイルハンドルの配列。
+     * @param mode ファイルのオプション。
+     * @returns 成功した場合は`WebFsFileHandleList`、エラーが出た場合は`undefined`。
+     */
+    static create(handles: FileSystemFileHandle[], mode?: FileSystemPermissionMode): Promise<WebFsFileHandleList | undefined>;
+    /**
+     * ファイルを取得します。
+     *
+     * @param fileName 取得するファイルのファイル名。
+     * @returns ファイルが取得できた場合は`WebFsFileHandle`、存在しない場合は`undefined`。
+     */
+    file(fileName: string): WebFsFileHandle | undefined;
+    /**
+     * ファイル名の一覧を取得します。
+     *
+     * @returns ファイル名の配列を返します。
+     */
+    names(): string[];
+    /**
+     * ファイルハンドルの一覧を取得します。
+     *
+     * @returns ファイルハンドルの配列を返します。
+     */
+    list(): WebFsFileHandle[];
+    /**
+     * 現在の`WebFsFileHandleList`インスタンスが管理しているファイルハンドルの数を取得します。
+     */
+    get length(): number;
+    [Symbol.iterator](): Generator<WebFsFileHandle, void, unknown>;
+}
+
+/** ハッシュ化するアルゴリズムの種類です。 */
+export declare type WebFsFileHashType = "md5" | "sha256" | "sha512";
+
+export declare interface WebFsFileInfo {
+    /** ファイルの名前です。 */
+    name: string;
+    /** ファイルサイズです。単位はバイトです。 */
+    size: number;
+    /** ファイルのMIMEタイプです。 */
+    mimeType: string;
+    /** ファイルの最終更新日時です。 */
+    lastModified: number;
+}
+
+/** ファイルを選択する際のオプションです。 */
+export declare type WebFsFilePickOptions = WebFsPickOptions & {
+    /** 指定されている拡張子とは別に、すべての拡張子を許可する項目を追加します。 */
+    acceptAllExtensions?: boolean;
+};
+
+/** ファイルの種類を定義するオブジェクトです。 */
+export declare interface WebFsFilePickType {
+    /** ファイルの種類の、ユーザー向けの説明です。 */
+    description?: string;
+    /** 許可するMIMEタイプと拡張子のリストです。 */
+    accept: FileExtension[];
+}
+
+/** ディレクトリを取得する際のオプションです。 */
+export declare interface WebFsGetDirectoryOptions extends FileSystemGetDirectoryOptions, WebFsPermissionOptions {
+}
+
+/** ファイルを取得する際のオプションです。 */
+export declare interface WebFsGetFileOptions extends FileSystemGetFileOptions, WebFsPermissionOptions {
+}
+
+export declare abstract class WebFsHandle {
+    abstract readonly type: "file" | "directory";
+    protected _handle: FileSystemHandle;
+    protected constructor(handle: FileSystemHandle);
+    /**
+     * ファイルハンドルの名前。ファイル名やディレクトリ名を表します。
+     */
+    get name(): string;
+    protected _verifyPermission(mode: FileSystemPermissionMode): Promise<boolean>;
+}
+
+/** 権限に関するオプションです。 */
+export declare interface WebFsPermissionOptions {
+    /** ファイルやディレクトリに対する権限を、`"read"`または`"readwrite"`で指定します。 */
+    mode?: FileSystemPermissionMode;
+}
+
+/** ファイルやディレクトリを選択する際の共通オプションです。 */
+export declare type WebFsPickOptions = {
+    /** ファイルやディレクトリに対する権限を、`"read"`または`"readwrite"`で指定します。 */
+    mode?: FileSystemPermissionMode;
+    /** ダイアログを開く際の初期ディレクトリを指定します。 */
+    startIn?: WellKnownDirectory;
+    /** 選択可能なファイルの種類を指定します。 */
+    types?: WebFsFilePickType[];
+} & ({
+    /** 設定を保存するためのIDです。 */
+    id: string;
+    /** 永続化するかどうかを指定します。 */
+    persistence: true;
+} | {
+    /** 設定を保存するためのIDです。 */
+    id?: string;
+    /** 永続化するかどうかを指定します。 */
+    persistence?: false;
+});
+
+/** ツリー形式のファイル構造を表すオブジェクトです。 */
+export declare type WebFsTreeResult = {
+    /** ディレクトリハンドルです。 */
+    handle: FileSystemFileHandle;
+    /** ディレクトリ内の子要素のリストです。 */
+    children: undefined;
+} | {
+    /** ディレクトリハンドルです。 */
+    handle: FileSystemDirectoryHandle;
+    /** ディレクトリ内の子要素のリストです。 */
+    children: WebFsTreeResult[];
+};
+
+export { }