@fgv/ts-http-storage 5.1.0-2 → 5.1.0-20

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

@@ -1,26 +0,0 @@
-Invoking: heft test --clean 
- ---- build started ---- 
-[build:clean] Deleted 0 files and 3 folders
-[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.589s) ---- 
- ---- test started ---- 
-[test:jest] Using Jest version 29.5.0
-[test:jest] 
-[test:jest] Run start. 3 test suites
-[test:jest] START lib/test/unit/storage/routes.test.js
-[test:jest] START lib/test/unit/storage/fsProvider.test.js
-[test:jest] START lib/test/unit/storage/service.test.js
-[test:jest] PASS lib/test/unit/storage/service.test.js (duration: 0.151s, 3 passed, 0 failed)
-[test:jest] PASS lib/test/unit/storage/routes.test.js (duration: 0.160s, 4 passed, 0 failed)
-[test:jest] PASS lib/test/unit/storage/fsProvider.test.js (duration: 0.160s, 10 passed, 0 failed)
-[test:jest] 
-[test:jest] Tests finished:
-[test:jest]   Successes: 17
-[test:jest]   Failures: 0
-[test:jest]   Total: 17
- ---- test finished (0.531s) ---- 
--------------------- Finished (3.123s) --------------------

package/src/index.ts

@@ -1,28 +0,0 @@
-/*
- * 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

@@ -1,100 +0,0 @@
-/*
- * 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

@@ -1,263 +0,0 @@
-/*
- * 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

@@ -1,33 +0,0 @@
-/*
- * 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';

package/src/packlets/storage/model.ts

@@ -1,113 +0,0 @@
-/*
- * 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 { Result } from '@fgv/ts-utils';
-
-/**
- * Namespace identifier for scoped storage.
- * @public
- */
-export type StorageNamespace = string;
-
-/**
- * Storage item type.
- * @public
- */
-export type StorageItemType = 'file' | 'directory';
-
-/**
- * Storage tree item metadata.
- * @public
- */
-export interface IStorageTreeItem {
-  readonly path: string;
-  readonly name: string;
-  readonly type: StorageItemType;
-}
-
-/**
- * Response for listing children.
- * @public
- */
-export interface IStorageTreeChildrenResponse {
-  readonly path: string;
-  readonly children: ReadonlyArray<IStorageTreeItem>;
-}
-
-/**
- * Response for reading a file.
- * @public
- */
-export interface IStorageFileResponse {
-  readonly path: string;
-  readonly contents: string;
-  readonly contentType?: string;
-}
-
-/**
- * Request for path-based operations.
- * @public
- */
-export interface IStoragePathRequest {
-  readonly path: string;
-  readonly namespace?: StorageNamespace;
-}
-
-/**
- * Request for writing file contents.
- * @public
- */
-export interface IStorageWriteFileRequest extends IStoragePathRequest {
-  readonly contents: string;
-  readonly contentType?: string;
-}
-
-/**
- * Request for sync operation.
- * @public
- */
-export interface IStorageSyncRequest {
-  readonly namespace?: StorageNamespace;
-}
-
-/**
- * Sync response metadata.
- * @public
- */
-export interface IStorageSyncResponse {
-  readonly synced: number;
-}
-
-/**
- * Provider contract for storage backends.
- * All methods are async to support both filesystem and database backends.
- * @public
- */
-export interface IHttpStorageProvider {
-  getItem(path: string): Promise<Result<IStorageTreeItem>>;
-  getChildren(path: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>>;
-  getFile(path: string): Promise<Result<IStorageFileResponse>>;
-  saveFile(path: string, contents: string, contentType?: string): Promise<Result<IStorageFileResponse>>;
-  deleteFile(path: string): Promise<Result<boolean>>;
-  createDirectory(path: string): Promise<Result<IStorageTreeItem>>;
-  sync(): Promise<Result<IStorageSyncResponse>>;
-}

package/src/packlets/storage/provider.ts

@@ -1,33 +0,0 @@
-/*
- * 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 { Result } from '@fgv/ts-utils';
-
-import type { IHttpStorageProvider, StorageNamespace } from './model';
-
-/**
- * Factory for creating namespace-scoped storage providers.
- * @public
- */
-export interface IHttpStorageProviderFactory {
-  forNamespace(namespace?: StorageNamespace): Result<IHttpStorageProvider>;
-}