@fgv/ts-http-storage 5.1.0-1

package/lib/test/unit/storage/service.test.d.ts

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=service.test.d.ts.map

package/lib/test/unit/storage/service.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.test.d.ts","sourceRoot":"","sources":["../../../../src/test/unit/storage/service.test.ts"],"names":[],"mappings":""}

package/lib/test/unit/storage/service.test.js

@@ -0,0 +1,67 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const ts_utils_1 = require("@fgv/ts-utils");
+const storage_1 = require("../../../packlets/storage");
+class StubProvider {
+    async getItem(path) {
+        return (0, ts_utils_1.succeed)({ path, name: 'item', type: 'file' });
+    }
+    async getChildren(path) {
+        return (0, ts_utils_1.succeed)([{ path: `${path}/child.txt`, name: 'child.txt', type: 'file' }]);
+    }
+    async getFile(path) {
+        return (0, ts_utils_1.succeed)({ path, contents: 'contents' });
+    }
+    async saveFile(path, contents, contentType) {
+        return (0, ts_utils_1.succeed)({ path, contents, contentType });
+    }
+    async deleteFile(_path) {
+        return (0, ts_utils_1.succeed)(true);
+    }
+    async createDirectory(path) {
+        return (0, ts_utils_1.succeed)({ path, name: 'created', type: 'directory' });
+    }
+    async sync() {
+        return (0, ts_utils_1.succeed)({ synced: 7 });
+    }
+}
+class StubProviderFactory {
+    constructor(provider) {
+        this._provider = provider;
+    }
+    forNamespace() {
+        return (0, ts_utils_1.succeed)(this._provider);
+    }
+}
+class FailingProviderFactory {
+    forNamespace() {
+        return (0, ts_utils_1.fail)('missing provider');
+    }
+}
+describe('HttpStorageService', () => {
+    test('maps getChildren response shape', async () => {
+        const service = new storage_1.HttpStorageService(new StubProviderFactory(new StubProvider()));
+        const result = await service.getChildren({ path: '/data', namespace: 'default' });
+        expect(result.isSuccess()).toBe(true);
+        expect(result.orThrow()).toEqual({
+            path: '/data',
+            children: [{ path: '/data/child.txt', name: 'child.txt', type: 'file' }]
+        });
+    });
+    test('formats provider lookup failures', async () => {
+        const service = new storage_1.HttpStorageService(new FailingProviderFactory());
+        const getResult = await service.getFile({ path: '/missing', namespace: 'default' });
+        expect(getResult.isFailure()).toBe(true);
+        expect(getResult.message).toBe('provider: missing provider');
+        const syncResult = await service.sync({ namespace: 'default' });
+        expect(syncResult.isFailure()).toBe(true);
+        expect(syncResult.message).toBe('provider: missing provider');
+    });
+    test('forwards deleteFile to provider', async () => {
+        const service = new storage_1.HttpStorageService(new StubProviderFactory(new StubProvider()));
+        const result = await service.deleteFile({ path: '/data/remove.txt', namespace: 'default' });
+        expect(result.isSuccess()).toBe(true);
+        expect(result.orThrow()).toBe(true);
+    });
+});
+//# sourceMappingURL=service.test.js.map

package/lib/test/unit/storage/service.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"service.test.js","sourceRoot":"","sources":["../../../../src/test/unit/storage/service.test.ts"],"names":[],"mappings":"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","sourcesContent":["import { fail, type Result, succeed } from '@fgv/ts-utils';\n\nimport {\n  HttpStorageService,\n  type IHttpStorageProvider,\n  type IHttpStorageProviderFactory,\n  type IStorageFileResponse,\n  type IStorageSyncResponse,\n  type IStorageTreeItem\n} from '../../../packlets/storage';\n\nclass StubProvider implements IHttpStorageProvider {\n  public async getItem(path: string): Promise<Result<IStorageTreeItem>> {\n    return succeed({ path, name: 'item', type: 'file' });\n  }\n\n  public async getChildren(path: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>> {\n    return succeed([{ path: `${path}/child.txt`, name: 'child.txt', type: 'file' }]);\n  }\n\n  public async getFile(path: string): Promise<Result<IStorageFileResponse>> {\n    return succeed({ path, contents: 'contents' });\n  }\n\n  public async saveFile(\n    path: string,\n    contents: string,\n    contentType?: string\n  ): Promise<Result<IStorageFileResponse>> {\n    return succeed({ path, contents, contentType });\n  }\n\n  public async deleteFile(_path: string): Promise<Result<boolean>> {\n    return succeed(true);\n  }\n\n  public async createDirectory(path: string): Promise<Result<IStorageTreeItem>> {\n    return succeed({ path, name: 'created', type: 'directory' });\n  }\n\n  public async sync(): Promise<Result<IStorageSyncResponse>> {\n    return succeed({ synced: 7 });\n  }\n}\n\nclass StubProviderFactory implements IHttpStorageProviderFactory {\n  private readonly _provider: IHttpStorageProvider;\n\n  public constructor(provider: IHttpStorageProvider) {\n    this._provider = provider;\n  }\n\n  public forNamespace(): Result<IHttpStorageProvider> {\n    return succeed(this._provider);\n  }\n}\n\nclass FailingProviderFactory implements IHttpStorageProviderFactory {\n  public forNamespace(): Result<IHttpStorageProvider> {\n    return fail('missing provider');\n  }\n}\n\ndescribe('HttpStorageService', () => {\n  test('maps getChildren response shape', async () => {\n    const service = new HttpStorageService(new StubProviderFactory(new StubProvider()));\n\n    const result = await service.getChildren({ path: '/data', namespace: 'default' });\n    expect(result.isSuccess()).toBe(true);\n    expect(result.orThrow()).toEqual({\n      path: '/data',\n      children: [{ path: '/data/child.txt', name: 'child.txt', type: 'file' }]\n    });\n  });\n\n  test('formats provider lookup failures', async () => {\n    const service = new HttpStorageService(new FailingProviderFactory());\n\n    const getResult = await service.getFile({ path: '/missing', namespace: 'default' });\n    expect(getResult.isFailure()).toBe(true);\n    expect(getResult.message).toBe('provider: missing provider');\n\n    const syncResult = await service.sync({ namespace: 'default' });\n    expect(syncResult.isFailure()).toBe(true);\n    expect(syncResult.message).toBe('provider: missing provider');\n  });\n\n  test('forwards deleteFile to provider', async () => {\n    const service = new HttpStorageService(new StubProviderFactory(new StubProvider()));\n\n    const result = await service.deleteFile({ path: '/data/remove.txt', namespace: 'default' });\n    expect(result.isSuccess()).toBe(true);\n    expect(result.orThrow()).toBe(true);\n  });\n});\n"]}

package/package.json

@@ -0,0 +1,66 @@
+{
+  "name": "@fgv/ts-http-storage",
+  "version": "5.1.0-1",
+  "description": "Reusable HTTP storage services for FileTree-style backends",
+  "main": "lib/index.js",
+  "types": "dist/ts-http-storage.d.ts",
+  "exports": {
+    ".": {
+      "node": {
+        "import": "./lib/index.js",
+        "require": "./lib/index.js"
+      },
+      "default": {
+        "import": "./lib/index.js",
+        "require": "./lib/index.js"
+      },
+      "types": "./dist/ts-http-storage.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "heft build --clean",
+    "clean": "heft clean",
+    "test": "heft test --clean",
+    "api-report": "api-extractor run --config ./config/api-extractor.json",
+    "api-report:update": "api-extractor run --local --config ./config/api-extractor.json",
+    "build-docs": "typedoc --options ./config/typedoc.json",
+    "build-all": "rushx build; rushx build-docs",
+    "coverage": "heft test --clean --coverage",
+    "lint": "eslint src --ext .ts",
+    "fixlint": "eslint src --ext .ts --fix"
+  },
+  "sideEffects": false,
+  "author": "Erik Fortune",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ErikFortune/fgv.git"
+  },
+  "dependencies": {
+    "@fgv/ts-utils": "workspace:*",
+    "hono": "~4.7.11"
+  },
+  "devDependencies": {
+    "@microsoft/api-documenter": "^7.28.2",
+    "@microsoft/api-extractor": "^7.55.2",
+    "@fgv/ts-utils-jest": "workspace:*",
+    "@rushstack/heft": "1.2.6",
+    "@rushstack/heft-node-rig": "2.11.26",
+    "@rushstack/eslint-config": "4.6.4",
+    "@types/heft-jest": "1.0.6",
+    "@types/jest": "^29.5.14",
+    "@types/node": "^20.14.9",
+    "@typescript-eslint/eslint-plugin": "^8.52.0",
+    "@typescript-eslint/parser": "^8.52.0",
+    "eslint": "^9.39.2",
+    "eslint-plugin-tsdoc": "~0.5.2",
+    "jest": "^29.7.0",
+    "ts-jest": "^29.4.6",
+    "typescript": "5.9.3",
+    "typedoc": "~0.28.16",
+    "typedoc-plugin-markdown": "~4.9.0",
+    "@rushstack/heft-jest-plugin": "1.2.6",
+    "@fgv/heft-dual-rig": "workspace:*",
+    "@fgv/typedoc-compact-theme": "workspace:*"
+  }
+}

package/rush-logs/ts-http-storage.build.cache.log

@@ -0,0 +1,3 @@
+Caching build output folders: dist, lib, temp, .rush/temp/operation/build
+Successfully set cache entry.
+Cache key: fbfcc9487d290993ba47f1d36e9383196e7b12ac

package/rush-logs/ts-http-storage.build.log

@@ -0,0 +1,9 @@
+Invoking: heft build --clean 
+ ---- build started ---- 
+[build:typescript] The TypeScript compiler version 5.9.3 is newer than the latest version that was tested with Heft (5.8); it may not work correctly.
+[build:typescript] Using TypeScript version 5.9.3
+[build:api-extractor] Using API Extractor version 7.57.6
+[build:api-extractor] Analysis will use the bundled TypeScript version 5.8.2
+[build:api-extractor] *** The target project appears to use TypeScript 5.9.3 which is newer than the bundled compiler engine; consider upgrading API Extractor.
+ ---- build finished (2.615s) ---- 
+-------------------- Finished (2.617s) --------------------

package/src/index.ts

@@ -0,0 +1,28 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * 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.
+ */
+
+/**
+ * Reusable HTTP storage services for FileTree-style backends.
+ * @packageDocumentation
+ */
+
+export * from './packlets/storage';

package/src/packlets/storage/converters.ts

@@ -0,0 +1,100 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * 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.
+ */
+
+import { type Converter, Converters } from '@fgv/ts-utils';
+
+import type {
+  IStorageFileResponse,
+  IStoragePathRequest,
+  IStorageSyncRequest,
+  IStorageTreeChildrenResponse,
+  IStorageTreeItem,
+  IStorageWriteFileRequest,
+  StorageItemType
+} from './model';
+
+const storageItemType: Converter<StorageItemType> = Converters.enumeratedValue<StorageItemType>([
+  'file',
+  'directory'
+]);
+
+/**
+ * Converter for {@link IStorageTreeItem}.
+ * @public
+ */
+export const storageTreeItem: Converter<IStorageTreeItem> = Converters.strictObject<IStorageTreeItem>({
+  path: Converters.string,
+  name: Converters.string,
+  type: storageItemType
+});
+
+/**
+ * Converter for path-based requests.
+ * @public
+ */
+export const storagePathRequest: Converter<IStoragePathRequest> =
+  Converters.strictObject<IStoragePathRequest>({
+    path: Converters.string,
+    namespace: Converters.string.optional()
+  });
+
+/**
+ * Converter for write-file requests.
+ * @public
+ */
+export const storageWriteFileRequest: Converter<IStorageWriteFileRequest> =
+  Converters.strictObject<IStorageWriteFileRequest>({
+    path: Converters.string,
+    contents: Converters.string,
+    contentType: Converters.string.optional(),
+    namespace: Converters.string.optional()
+  });
+
+/**
+ * Converter for sync requests.
+ * @public
+ */
+export const storageSyncRequest: Converter<IStorageSyncRequest> =
+  Converters.strictObject<IStorageSyncRequest>({
+    namespace: Converters.string.optional()
+  });
+
+/**
+ * Converter for file responses.
+ * @public
+ */
+export const storageFileResponse: Converter<IStorageFileResponse> =
+  Converters.strictObject<IStorageFileResponse>({
+    path: Converters.string,
+    contents: Converters.string,
+    contentType: Converters.string.optional()
+  });
+
+/**
+ * Converter for children list responses.
+ * @public
+ */
+export const storageTreeChildrenResponse: Converter<IStorageTreeChildrenResponse> =
+  Converters.strictObject<IStorageTreeChildrenResponse>({
+    path: Converters.string,
+    children: Converters.arrayOf(storageTreeItem)
+  });

package/src/packlets/storage/fsProvider.ts

@@ -0,0 +1,263 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * 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.
+ */
+
+import * as fs from 'fs';
+import * as fsp from 'fs/promises';
+import * as path from 'path';
+
+import { captureResult, fail, type Result, succeed } from '@fgv/ts-utils';
+
+import type {
+  IHttpStorageProvider,
+  IStorageFileResponse,
+  IStorageSyncResponse,
+  IStorageTreeItem,
+  StorageItemType
+} from './model';
+import type { IHttpStorageProviderFactory } from './provider';
+
+/**
+ * Options for creating filesystem-backed storage providers.
+ * @public
+ */
+export interface IFsStorageProviderFactoryOptions {
+  readonly rootPath: string;
+}
+
+function toItemType(stats: fs.Stats): StorageItemType {
+  return stats.isDirectory() ? 'directory' : 'file';
+}
+
+/**
+ * Filesystem-backed implementation of {@link IHttpStorageProvider}.
+ * @public
+ */
+export class FsStorageProvider implements IHttpStorageProvider {
+  private readonly _rootPath: string;
+
+  public constructor(rootPath: string) {
+    this._rootPath = rootPath;
+  }
+
+  public async getItem(itemPath: string): Promise<Result<IStorageTreeItem>> {
+    const resolved = this._resolveAbsolutePath(itemPath);
+    if (resolved.isFailure()) {
+      return fail(resolved.message);
+    }
+    try {
+      const stats = await fsp.stat(resolved.value);
+      return succeed(this._toTreeItem(itemPath, toItemType(stats)));
+    } catch (err: unknown) {
+      return fail(`${itemPath}: ${_toMessage(err)}`);
+    }
+  }
+
+  public async getChildren(itemPath: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>> {
+    const resolved = this._resolveAbsolutePath(itemPath);
+    if (resolved.isFailure()) {
+      return fail(resolved.message);
+    }
+    try {
+      const entries = await fsp.readdir(resolved.value, { withFileTypes: true });
+      return _mapEntries(entries, itemPath);
+    } catch (err: unknown) {
+      return fail(`${itemPath}: ${_toMessage(err)}`);
+    }
+  }
+
+  public async getFile(itemPath: string): Promise<Result<IStorageFileResponse>> {
+    const resolved = this._resolveAbsolutePath(itemPath);
+    if (resolved.isFailure()) {
+      return fail(resolved.message);
+    }
+    try {
+      const stats = await fsp.stat(resolved.value);
+      if (!stats.isFile()) {
+        return fail(`${itemPath}: not a file`);
+      }
+      const contents = await fsp.readFile(resolved.value, 'utf8');
+      return succeed({
+        path: normalizeRequestPath(itemPath),
+        contents
+      });
+    } catch (err: unknown) {
+      return fail(`${itemPath}: ${_toMessage(err)}`);
+    }
+  }
+
+  public async saveFile(
+    itemPath: string,
+    contents: string,
+    contentType?: string
+  ): Promise<Result<IStorageFileResponse>> {
+    const resolved = this._resolveAbsolutePath(itemPath);
+    if (resolved.isFailure()) {
+      return fail(resolved.message);
+    }
+    try {
+      const parentDir = path.dirname(resolved.value);
+      await fsp.mkdir(parentDir, { recursive: true });
+      await fsp.writeFile(resolved.value, contents, 'utf8');
+      return succeed({
+        path: normalizeRequestPath(itemPath),
+        contents,
+        contentType
+      });
+    } catch (err: unknown) {
+      return fail(`${itemPath}: ${_toMessage(err)}`);
+    }
+  }
+
+  public async deleteFile(itemPath: string): Promise<Result<boolean>> {
+    const resolved = this._resolveAbsolutePath(itemPath);
+    if (resolved.isFailure()) {
+      return fail(resolved.message);
+    }
+    try {
+      const stats = await fsp.stat(resolved.value);
+      if (!stats.isFile()) {
+        return fail(`${itemPath}: not a file`);
+      }
+      await fsp.unlink(resolved.value);
+      return succeed(true);
+    } catch (err: unknown) {
+      return fail(`${itemPath}: ${_toMessage(err)}`);
+    }
+  }
+
+  public async createDirectory(itemPath: string): Promise<Result<IStorageTreeItem>> {
+    const resolved = this._resolveAbsolutePath(itemPath);
+    if (resolved.isFailure()) {
+      return fail(resolved.message);
+    }
+    try {
+      await fsp.mkdir(resolved.value, { recursive: true });
+      return succeed(this._toTreeItem(itemPath, 'directory'));
+    } catch (err: unknown) {
+      return fail(`${itemPath}: ${_toMessage(err)}`);
+    }
+  }
+
+  public async sync(): Promise<Result<IStorageSyncResponse>> {
+    return succeed({ synced: 0 });
+  }
+
+  private _resolveAbsolutePath(requestPath: string): Result<string> {
+    const normalized = normalizeRequestPath(requestPath);
+    const candidate = path.resolve(this._rootPath, `.${normalized}`);
+    const relative = path.relative(this._rootPath, candidate);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+      return fail(`${requestPath}: path is outside storage root`);
+    }
+    return succeed(candidate);
+  }
+
+  private _toTreeItem(itemPath: string, type: StorageItemType): IStorageTreeItem {
+    const normalizedPath = normalizeRequestPath(itemPath);
+    const name = normalizedPath === '/' ? '/' : path.posix.basename(normalizedPath);
+    return {
+      path: normalizedPath,
+      name,
+      type
+    };
+  }
+}
+
+function _mapEntries(
+  entries: ReadonlyArray<fs.Dirent>,
+  parentPath: string
+): Result<ReadonlyArray<IStorageTreeItem>> {
+  const normalizedParent = normalizeRequestPath(parentPath);
+  const items: IStorageTreeItem[] = entries.map((entry) => {
+    const isDirectory = entry.isDirectory();
+    const childPath = normalizedParent === '/' ? `/${entry.name}` : `${normalizedParent}/${entry.name}`;
+    return {
+      path: childPath,
+      name: entry.name,
+      type: isDirectory ? 'directory' : 'file'
+    };
+  });
+  return succeed(items);
+}
+
+function _toMessage(err: unknown): string {
+  return err instanceof Error ? err.message : String(err);
+}
+
+/**
+ * Normalizes a request path to a consistent POSIX format.
+ * @public
+ */
+export function normalizeRequestPath(requestPath: string): string {
+  if (requestPath.length === 0) {
+    return '/';
+  }
+  const normalized = path.posix.normalize(requestPath.startsWith('/') ? requestPath : `/${requestPath}`);
+  return normalized.startsWith('/') ? normalized : `/${normalized}`;
+}
+
+/**
+ * Namespace-aware provider factory backed by filesystem directories.
+ * @public
+ */
+export class FsStorageProviderFactory implements IHttpStorageProviderFactory {
+  private readonly _rootPath: string;
+
+  public constructor(options: IFsStorageProviderFactoryOptions) {
+    this._rootPath = path.resolve(options.rootPath);
+  }
+
+  public forNamespace(namespace?: string): Result<IHttpStorageProvider> {
+    const safeNamespace = sanitizeNamespace(namespace);
+    if (safeNamespace.isFailure()) {
+      return fail(safeNamespace.message);
+    }
+
+    const namespaceRoot = path.resolve(this._rootPath, safeNamespace.value);
+    const relative = path.relative(this._rootPath, namespaceRoot);
+    if (relative.startsWith('..') || path.isAbsolute(relative)) {
+      return fail(`namespace '${safeNamespace.value}' is outside root`);
+    }
+
+    const ensureResult = captureResult(() => fs.mkdirSync(namespaceRoot, { recursive: true }));
+    if (ensureResult.isFailure()) {
+      return fail(`namespace '${safeNamespace.value}': ${ensureResult.message}`);
+    }
+
+    return succeed(new FsStorageProvider(namespaceRoot));
+  }
+}
+
+/**
+ * Sanitize namespace path segment.
+ * @public
+ */
+export function sanitizeNamespace(namespace?: string): Result<string> {
+  if (!namespace || namespace.trim().length === 0) {
+    return succeed('default');
+  }
+  const trimmed = namespace.trim();
+  if (!/^[a-zA-Z0-9._-]+$/.test(trimmed)) {
+    return fail(`namespace '${namespace}': only [a-zA-Z0-9._-] allowed`);
+  }
+  return succeed(trimmed);
+}

package/src/packlets/storage/index.ts

@@ -0,0 +1,33 @@
+/*
+ * Copyright (c) 2026 Erik Fortune
+ *
+ * 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.
+ */
+
+/**
+ * Reusable HTTP storage services and route helpers.
+ * @packageDocumentation
+ */
+
+export * from './model';
+export * from './converters';
+export * from './provider';
+export * from './fsProvider';
+export * from './service';
+export * from './routes';