@mad-c/file-system-helpers 1.0.0

package/dist/path.js

@@ -0,0 +1,180 @@
+/**
+ * Split a path string into segments and normalize it.
+ *
+ * The normalization does the following:
+ * - Removes empty path segments.
+ * - Decode from URI parts to handle paths coming from URLs.
+ *
+ * @param path The path to split into segments
+ */
+export function pathToSegments(path) {
+    const segments = path.split('/').filter(Boolean).map((part) => part.trim());
+    return segments;
+}
+/**
+ * Returns the directory name, given a path string.
+ * It is similar to node's `dirname` fucntion.
+ *
+ * @param path The path to get the directory name
+ */
+export function dirname(path) {
+    const segments = pathToSegments(path);
+    const pathBase = path.startsWith('/') ? '/' : '';
+    if (segments.length <= 1) {
+        return pathBase;
+    }
+    const dirSegments = segments.slice(0, -1);
+    return `${pathBase}${dirSegments.join('/')}`;
+}
+/**
+ * Returns the name for the last part of a given path string.
+ * It is similar to node's `basename` function.
+ *
+ * @param path The path to get the last part.
+ * @param suffix An optional extension to remove from the item, like an extension.
+ */
+export function basename(path, suffix) {
+    const segments = pathToSegments(path);
+    const lastSegment = segments.at(-1) ?? '';
+    if (suffix && lastSegment.endsWith(suffix)) {
+        return lastSegment.slice(0, -suffix.length);
+    }
+    return lastSegment;
+}
+/**
+ * Returns the extension of the path, from the last occurrence of the `.` (dot) to the end of the string.
+ * Returns an empty string if there is no dot or if the only dot is in the start of the string.
+ * It is similar to node's `extname` function.
+ *
+ * @param path The path to get the extension
+ */
+export function extname(path) {
+    const base = basename(path);
+    const index = base.lastIndexOf('.');
+    if (index <= 0) {
+        return '';
+    }
+    return base.slice(index);
+}
+/**
+ * Resolves a sequence of paths or path segments into an absolute path.
+ * It is similar to node's `resolve` function.
+ *
+ * **Note**: If no absolute path is provided, the function prepends a `/`. It assumes the starting point is _always_ the file system root.
+ *
+ * @param paths A sequence of paths or path segments
+ */
+export function resolve(...paths) {
+    // INfO: start by concatenating all paths
+    let fullPath = '';
+    for (const path of paths) {
+        if (path.startsWith('/')) {
+            fullPath = path;
+        }
+        else {
+            fullPath = fullPath ? `${fullPath}/${path}` : path;
+        }
+    }
+    // INFO: prepend initial dash
+    if (!fullPath.startsWith('/')) {
+        fullPath = `/${fullPath}`;
+    }
+    // INFO: resolve `..`, `.`, and empty segments
+    const stack = [];
+    const segments = pathToSegments(fullPath);
+    for (const segment of segments) {
+        if (segment === '..') {
+            stack.pop();
+        }
+        else if (segment !== '.' && segment !== '') {
+            stack.push(segment);
+        }
+    }
+    return `/${stack.join('/')}`;
+}
+const RESTRICTED_NAMES = [
+    'CON',
+    'PRN',
+    'AUX',
+    'NUL',
+    'COM1',
+    'COM2',
+    'COM3',
+    'COM4',
+    'COM5',
+    'COM6',
+    'COM7',
+    'COM8',
+    'COM9',
+    'LPT1',
+    'LPT2',
+    'LPT3',
+    'LPT4',
+    'LPT5',
+    'LPT6',
+    'LPT7',
+    'LPT8',
+    'LPT9'
+];
+const RESTRICTED_CHARACTERS = [
+    // INFO: C0 control characters
+    // oxlint-disable-next-line no-magic-numbers
+    ...new Array(32).fill('').map((_, i) => String.fromCharCode(i)),
+    // INFO: "del" character
+    '\x7f',
+    // INFO: C1 control characters
+    // oxlint-disable-next-line no-magic-numbers
+    ...new Array(32).fill('').map((_, i) => String.fromCharCode(128 + i)),
+    // INFO: characters not allowed on Windows/Linux/Mac
+    ...['*', '"', '/', '\\', '>', '<', ':', '|', '?', "'"],
+    // INFO: also add "%" to make it easier to decode lone "%" symbols
+    '%'
+];
+function defaultEncodeReplacer(segment) {
+    const trimmedSegment = segment.trim();
+    if (trimmedSegment === '..') {
+        return '%2e%2e';
+    }
+    if (trimmedSegment === '.') {
+        return '%2e';
+    }
+    if (RESTRICTED_NAMES.includes(trimmedSegment)) {
+        // oxlint-disable-next-line typescript/no-misused-spread
+        return [...trimmedSegment].map((char) => `%${char.charCodeAt(0).toString(16)}`).join('');
+    }
+    // oxlint-disable-next-line typescript/no-misused-spread
+    const codePoints = [...trimmedSegment];
+    let normalizedSegment = '';
+    for (const codePoint of codePoints) {
+        if (RESTRICTED_CHARACTERS.includes(codePoint)) {
+            normalizedSegment += `%${codePoint.charCodeAt(0).toString(16)}`;
+        }
+        else {
+            normalizedSegment += codePoint;
+        }
+    }
+    return normalizedSegment;
+}
+/**
+ * Encodes a path string, taking care of restricted characters and names and converting them to percent encoded characters.
+ *
+ * @param path The path to encode.
+ * @param replacer A custom replacer function that will be invoked for each segment of the path.
+ */
+export function encodePath(path, replacer) {
+    const segments = pathToSegments(path);
+    return segments.map((segment) => (replacer ?? defaultEncodeReplacer)(segment)).join('/');
+}
+function defaultDecodeReplacer(segment) {
+    return decodeURIComponent(segment.trim().replaceAll(/%(?![0-9a-fA-F]{2})/giu, '%25'));
+}
+/**
+ * Decodes a path string, converting back from perdent encoded characters.
+ *
+ * @param path The path to decode.
+ * @param replacer A custom replacer function that will be invoked for each segment of the path.
+ */
+export function decodePath(path, replacer) {
+    const segments = pathToSegments(path);
+    return segments.map((segment) => (replacer ?? defaultDecodeReplacer)(segment)).join('/');
+}

package/dist/permissions.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Get the current permission state for the handle.
+ *
+ * @param handle The handle to check permissions.
+ * @param permissions The permission type to check.
+ */
+export declare function getHandlePermisions(handle: FileSystemHandle, permissions?: FileSystemPermissionMode): Promise<PermissionState>;
+/**
+ * Checks and then request for permissions for a given handle.
+ *
+ * @param handle The handle to request permissions.
+ * @param permissions The permission type to get.
+ */
+export declare function requestHandlePermissions(handle: FileSystemHandle, permissions?: FileSystemPermissionMode): Promise<void>;

package/dist/permissions.js

@@ -0,0 +1,25 @@
+/**
+ * Get the current permission state for the handle.
+ *
+ * @param handle The handle to check permissions.
+ * @param permissions The permission type to check.
+ */
+export async function getHandlePermisions(handle, permissions = 'read') {
+    const permission = await handle.queryPermission({ mode: permissions });
+    return permission;
+}
+/**
+ * Checks and then request for permissions for a given handle.
+ *
+ * @param handle The handle to request permissions.
+ * @param permissions The permission type to get.
+ */
+export async function requestHandlePermissions(handle, permissions = 'read') {
+    const permission = await getHandlePermisions(handle, permissions);
+    if (permission !== 'granted') {
+        const request = await handle.requestPermission({ mode: permissions });
+        if (request !== 'granted') {
+            throw new Error('Permission to access the entry was denied');
+        }
+    }
+}

package/package.json

@@ -0,0 +1,48 @@
+{
+	"name": "@mad-c/file-system-helpers",
+	"version": "1.0.0",
+	"description": "Helpwer for working with the File System API",
+	"keywords": [
+		"file system",
+		"FS",
+		"browser file system",
+		"origin private file system",
+		"OPFS"
+	],
+	"author": "madcampos",
+	"license": "LGPL-2.1-or-later",
+	"type": "module",
+	"files": [
+		"dist"
+	],
+	"exports": {
+		".": "./dist/opfs.js",
+		"./path": "./dist/path.js",
+		"./permissions": "./dist/permissions.js",
+		"./access": "./dist/fs-access.js"
+	},
+	"scripts": {
+		"bootstrap": "playwright install chromium",
+		"build": "tsc --project tsconfig.build.json",
+		"format": "dprint fmt",
+		"typecheck": "tsc --noEmit",
+		"lint:js": "oxlint --fix",
+		"lint": "pnpm run typecheck && pnpm run lint:js",
+		"test": "vitest",
+		"changelog": "bumpy generate",
+		"prepublishOnly": "pnpm run build",
+		"bump-version": "bumpy version --commit",
+		"postbump-version": "bumpy publish"
+	},
+	"devDependencies": {
+		"@types/wicg-file-system-access": "^2023.10.7",
+		"@varlock/bumpy": "^1.18.0",
+		"@vitest/browser-playwright": "^4.1.9",
+		"@vitest/coverage-v8": "^4.1.9",
+		"dprint": "^0.54.0",
+		"oxlint": "^1.71.0",
+		"oxlint-tsgolint": "^0.23.0",
+		"typescript": "^6.0.3",
+		"vitest": "^4.1.9"
+	}
+}