@mad-c/file-system-helpers 1.0.0 → 1.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +93 -1
  2. package/package.json +27 -3
package/README.md CHANGED
@@ -1,3 +1,95 @@
1
1
  # file-system-helpers
2
2
 
3
- Helpers for working with the File System API
3
+ A collection of lightweight TypeScript helpers for the [File System API](https://developer.mozilla.org/en-US/docs/Web/API/File_System_API). Designed to simplify working with both the user-facing File System Access API and the Origin Private File System (OPFS).
4
+
5
+ ## Features
6
+
7
+ - **OPFS Helpers**: File and directory helper functions for common operations (read, save, copy, move, delete).
8
+ - **Path Utilities**: node.js inspired path manipulation functions.
9
+ - **File System Access Helpers**: Wrappers of `showOpenFilePicker`, `showSaveFilePicker`, and `showDirectoryPicker` with permission checking.
10
+ - **Persistence**: Store and retrieve `FileSystemHandle` objects in IndexedDB to maintain access across browser sessions.
11
+ - **Permissions Management**: Helpers to check and get permissions for files and directories.
12
+
13
+ ## Installation
14
+
15
+ ```bash
16
+ npm install @mad-c/file-system-helpers
17
+ ```
18
+
19
+ ## Usage
20
+
21
+ ### Origin Private File System (OPFS) Helpers
22
+
23
+ Resolve handles deeply within the OPFS structure.
24
+
25
+ ```typescript
26
+ import { getDirHandle, getFileHandle } from 'mad-file-system-helpers';
27
+
28
+ // Get a file handle, creating directories recursively and the file reference
29
+ const fileHandle = await getFileHandle('/path/to/my-file.txt', {
30
+ touch: true,
31
+ recursive: true
32
+ });
33
+
34
+ // Get a directory handle, creating directories recursively
35
+ const dirHandle = await getDirHandle('/projects/web/src', {
36
+ recursive: true
37
+ });
38
+ ```
39
+
40
+ ### Path Utilities
41
+
42
+ A set of path helpers inspired by node.js' `path` module but made to work directly with the browser and be easy to work with the OPFS.
43
+
44
+ > [!NOTE]
45
+ > All functions will use a forward slash (`/`) as the path separator.
46
+ > Browsers normalize paths to use this convention even on Windows.
47
+ > The path manipulation API is simplified byt not handling backslashes (`\`)
48
+
49
+ ```typescript
50
+ import { basename, dirname, extname, resolve } from 'mad-file-system-helpers';
51
+
52
+ basename('/path/to/file.txt'); // 'file.txt'
53
+ dirname('/path/to/file.txt'); // '/path/to'
54
+ extname('/path/to/file.txt'); // '.txt'
55
+ resolve('folder', 'subfolder', 'file.js'); // '/folder/subfolder/file.js'
56
+ ```
57
+
58
+ ### File System Access Helpers
59
+
60
+ > [!WARNING]
61
+ > This API is supported only on Chromium based browsers.
62
+
63
+ Improve interactions with the user's local file system.
64
+
65
+ ```typescript
66
+ import { getUserOpenFileHandle, getUserSaveFileHandle } from 'mad-file-system-helpers';
67
+
68
+ // Show the user a file picker with automatic permission handling
69
+ const handle = await getUserOpenFileHandle({
70
+ types: [{ description: 'Text files', accept: { 'text/plain': ['.txt'] } }]
71
+ }, 'readwrite');
72
+
73
+ if (handle) {
74
+ // Work with the handle...
75
+ }
76
+ ```
77
+
78
+ ### Persistence
79
+
80
+ [Saves handles to IndexedDB](https://developer.chrome.com/docs/capabilities/web-apis/file-system-access?authuser=1#permission_persistence) allowing to access the handle again on a new browser session (page reload, new tab, etc.).
81
+
82
+ ```typescript
83
+ import { getHandle, saveHandle } from 'mad-file-system-helpers';
84
+
85
+ // Save a handle, with a defined id, and any metadata.
86
+ await saveHandle('id-for-the-handle', handle, metadata);
87
+
88
+ // On another day, a new browser session...
89
+ const saved = await getHandle('id-for-the-handle');
90
+ if (saved) {
91
+ const { handle, metadata } = saved;
92
+
93
+ // Use the handle...
94
+ }
95
+ ```
package/package.json CHANGED
@@ -1,7 +1,7 @@
1
1
  {
2
2
  "name": "@mad-c/file-system-helpers",
3
- "version": "1.0.0",
4
- "description": "Helpwer for working with the File System API",
3
+ "version": "1.0.2",
4
+ "description": "Helper for working with the File System API",
5
5
  "keywords": [
6
6
  "file system",
7
7
  "FS",
@@ -9,8 +9,29 @@
9
9
  "origin private file system",
10
10
  "OPFS"
11
11
  ],
12
- "author": "madcampos",
12
+ "author": {
13
+ "name": "madcampos",
14
+ "url": "https://madcampos.dev/"
15
+ },
13
16
  "license": "LGPL-2.1-or-later",
17
+ "homepage": "https://github.com/madcampos/mad-file-system-helpers#readme",
18
+ "bugs": {
19
+ "url": "https://github.com/madcampos/mad-file-system-helpers/issues"
20
+ },
21
+ "repository": {
22
+ "type": "git",
23
+ "url": "git+https://github.com/madcampos/mad-file-system-helpers.git"
24
+ },
25
+ "funding": [
26
+ {
27
+ "type": "Buy Me a Coffee",
28
+ "url": "https://buymeacoffee.com/madcampos"
29
+ },
30
+ {
31
+ "type": "Ko-Fi",
32
+ "url": "https://ko-fi.com/madcampos"
33
+ }
34
+ ],
14
35
  "type": "module",
15
36
  "files": [
16
37
  "dist"
@@ -29,12 +50,14 @@
29
50
  "lint:js": "oxlint --fix",
30
51
  "lint": "pnpm run typecheck && pnpm run lint:js",
31
52
  "test": "vitest",
53
+ "docs": "node scripts/docs.ts",
32
54
  "changelog": "bumpy generate",
33
55
  "prepublishOnly": "pnpm run build",
34
56
  "bump-version": "bumpy version --commit",
35
57
  "postbump-version": "bumpy publish"
36
58
  },
37
59
  "devDependencies": {
60
+ "@types/node": "^26.0.1",
38
61
  "@types/wicg-file-system-access": "^2023.10.7",
39
62
  "@varlock/bumpy": "^1.18.0",
40
63
  "@vitest/browser-playwright": "^4.1.9",
@@ -42,6 +65,7 @@
42
65
  "dprint": "^0.54.0",
43
66
  "oxlint": "^1.71.0",
44
67
  "oxlint-tsgolint": "^0.23.0",
68
+ "tsdoc-markdown": "^1.5.0",
45
69
  "typescript": "^6.0.3",
46
70
  "vitest": "^4.1.9"
47
71
  }