@fgv/ts-http-storage 5.1.0-1

package/config/api-extractor.json

@@ -0,0 +1,36 @@
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/api-extractor/v7/api-extractor.schema.json",
+  "projectFolder": "..",
+  "mainEntryPointFilePath": "<projectFolder>/lib/index.d.ts",
+  "bundledPackages": [],
+  "apiReport": {
+    "enabled": true
+  },
+  "docModel": {
+    "enabled": true
+  },
+  "dtsRollup": {
+    "enabled": true
+  },
+  "messages": {
+    "compilerMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    },
+    "extractorMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      },
+      "ae-unresolved-link": {
+        "logLevel": "none",
+        "addToApiReportFile": true
+      }
+    },
+    "tsdocMessageReporting": {
+      "default": {
+        "logLevel": "warning"
+      }
+    }
+  }
+}

package/config/rig.json

@@ -0,0 +1,10 @@
+// The "rig.json" file directs tools to look for their config files in an external package.
+// Documentation for this system: https://www.npmjs.com/package/@rushstack/rig-package
+{
+  "$schema": "https://developer.microsoft.com/json-schemas/rig-package/rig.schema.json",
+  /**
+   * (Required) The name of the rig package to inherit from.
+   * It should be an NPM package name with the "-rig" suffix.
+   */
+  "rigPackageName": "@rushstack/heft-node-rig"
+}

package/config/typedoc.json

@@ -0,0 +1,7 @@
+{
+  "$schema": "https://typedoc.org/schema.json",
+  "extends": ["@fgv/heft-dual-rig/profiles/default/config/typedoc.compact-base.json"],
+  "plugin": ["../../../plugins/typedoc-compact-theme/lib/index.js"],
+  "entryPoints": ["../src/index.ts"],
+  "out": "../docs"
+}

package/dist/ts-http-storage.d.ts

@@ -0,0 +1,225 @@
+/**
+ * Reusable HTTP storage services for FileTree-style backends.
+ * @packageDocumentation
+ */
+
+import { Converter } from '@fgv/ts-utils';
+import { Hono } from 'hono';
+import type { Logging } from '@fgv/ts-utils';
+import { Result } from '@fgv/ts-utils';
+
+/**
+ * Builds storage routes for a Hono app.
+ * @public
+ */
+export declare function createStorageRoutes(options: ICreateStorageRoutesOptions): Hono;
+
+/**
+ * Filesystem-backed implementation of {@link IHttpStorageProvider}.
+ * @public
+ */
+export declare class FsStorageProvider implements IHttpStorageProvider {
+    private readonly _rootPath;
+    constructor(rootPath: string);
+    getItem(itemPath: string): Promise<Result<IStorageTreeItem>>;
+    getChildren(itemPath: string): Promise<Result<ReadonlyArray<IStorageTreeItem>>>;
+    getFile(itemPath: string): Promise<Result<IStorageFileResponse>>;
+    saveFile(itemPath: string, contents: string, contentType?: string): Promise<Result<IStorageFileResponse>>;
+    deleteFile(itemPath: string): Promise<Result<boolean>>;
+    createDirectory(itemPath: string): Promise<Result<IStorageTreeItem>>;
+    sync(): Promise<Result<IStorageSyncResponse>>;
+    private _resolveAbsolutePath;
+    private _toTreeItem;
+}
+
+/**
+ * Namespace-aware provider factory backed by filesystem directories.
+ * @public
+ */
+export declare class FsStorageProviderFactory implements IHttpStorageProviderFactory {
+    private readonly _rootPath;
+    constructor(options: IFsStorageProviderFactoryOptions);
+    forNamespace(namespace?: string): Result<IHttpStorageProvider>;
+}
+
+/**
+ * Service layer for storage API operations.
+ * @public
+ */
+export declare class HttpStorageService {
+    private readonly _providers;
+    constructor(providers: IHttpStorageProviderFactory);
+    getItem(request: IStoragePathRequest): Promise<Result<IStorageTreeItem>>;
+    getChildren(request: IStoragePathRequest): Promise<Result<IStorageTreeChildrenResponse>>;
+    getFile(request: IStoragePathRequest): Promise<Result<IStorageFileResponse>>;
+    saveFile(request: IStorageWriteFileRequest): Promise<Result<IStorageFileResponse>>;
+    deleteFile(request: IStoragePathRequest): Promise<Result<boolean>>;
+    createDirectory(request: IStoragePathRequest): Promise<Result<IStorageTreeItem>>;
+    sync(request: IStorageSyncRequest): Promise<Result<IStorageSyncResponse>>;
+    private _getProvider;
+}
+
+/**
+ * Options for creating storage routes.
+ * @public
+ */
+export declare interface ICreateStorageRoutesOptions {
+    readonly providers: IHttpStorageProviderFactory;
+    readonly logger?: Logging.ILogger;
+}
+
+/**
+ * Options for creating filesystem-backed storage providers.
+ * @public
+ */
+export declare interface IFsStorageProviderFactoryOptions {
+    readonly rootPath: string;
+}
+
+/**
+ * Provider contract for storage backends.
+ * All methods are async to support both filesystem and database backends.
+ * @public
+ */
+export declare 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>>;
+}
+
+/**
+ * Factory for creating namespace-scoped storage providers.
+ * @public
+ */
+export declare interface IHttpStorageProviderFactory {
+    forNamespace(namespace?: StorageNamespace): Result<IHttpStorageProvider>;
+}
+
+/**
+ * Response for reading a file.
+ * @public
+ */
+export declare interface IStorageFileResponse {
+    readonly path: string;
+    readonly contents: string;
+    readonly contentType?: string;
+}
+
+/**
+ * Request for path-based operations.
+ * @public
+ */
+export declare interface IStoragePathRequest {
+    readonly path: string;
+    readonly namespace?: StorageNamespace;
+}
+
+/**
+ * Request for sync operation.
+ * @public
+ */
+export declare interface IStorageSyncRequest {
+    readonly namespace?: StorageNamespace;
+}
+
+/**
+ * Sync response metadata.
+ * @public
+ */
+export declare interface IStorageSyncResponse {
+    readonly synced: number;
+}
+
+/**
+ * Response for listing children.
+ * @public
+ */
+export declare interface IStorageTreeChildrenResponse {
+    readonly path: string;
+    readonly children: ReadonlyArray<IStorageTreeItem>;
+}
+
+/**
+ * Storage tree item metadata.
+ * @public
+ */
+export declare interface IStorageTreeItem {
+    readonly path: string;
+    readonly name: string;
+    readonly type: StorageItemType;
+}
+
+/**
+ * Request for writing file contents.
+ * @public
+ */
+export declare interface IStorageWriteFileRequest extends IStoragePathRequest {
+    readonly contents: string;
+    readonly contentType?: string;
+}
+
+/**
+ * Normalizes a request path to a consistent POSIX format.
+ * @public
+ */
+export declare function normalizeRequestPath(requestPath: string): string;
+
+/**
+ * Sanitize namespace path segment.
+ * @public
+ */
+export declare function sanitizeNamespace(namespace?: string): Result<string>;
+
+/**
+ * Converter for file responses.
+ * @public
+ */
+export declare const storageFileResponse: Converter<IStorageFileResponse>;
+
+/**
+ * Storage item type.
+ * @public
+ */
+export declare type StorageItemType = 'file' | 'directory';
+
+/**
+ * Namespace identifier for scoped storage.
+ * @public
+ */
+export declare type StorageNamespace = string;
+
+/**
+ * Converter for path-based requests.
+ * @public
+ */
+export declare const storagePathRequest: Converter<IStoragePathRequest>;
+
+/**
+ * Converter for sync requests.
+ * @public
+ */
+export declare const storageSyncRequest: Converter<IStorageSyncRequest>;
+
+/**
+ * Converter for children list responses.
+ * @public
+ */
+export declare const storageTreeChildrenResponse: Converter<IStorageTreeChildrenResponse>;
+
+/**
+ * Converter for {@link IStorageTreeItem}.
+ * @public
+ */
+export declare const storageTreeItem: Converter<IStorageTreeItem>;
+
+/**
+ * Converter for write-file requests.
+ * @public
+ */
+export declare const storageWriteFileRequest: Converter<IStorageWriteFileRequest>;
+
+export { }

package/dist/tsdoc-metadata.json

@@ -0,0 +1,11 @@
+// This file is read by tools that parse documentation comments conforming to the TSDoc standard.
+// It should be published with your NPM package.  It should not be tracked by Git.
+{
+  "tsdocVersion": "0.12",
+  "toolPackages": [
+    {
+      "packageName": "@microsoft/api-extractor",
+      "packageVersion": "7.57.6"
+    }
+  ]
+}

package/docs/README.md

@@ -0,0 +1,298 @@
+# @fgv/ts-http-storage
+
+Reusable HTTP storage services for FileTree-style backends.
+
+## Classes
+
+<table><thead><tr><th>
+
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[FsStorageProvider](./classes/FsStorageProvider.md)
+
+</td><td>
+
+Filesystem-backed implementation of IHttpStorageProvider.
+
+</td></tr>
+<tr><td>
+
+[FsStorageProviderFactory](./classes/FsStorageProviderFactory.md)
+
+</td><td>
+
+Namespace-aware provider factory backed by filesystem directories.
+
+</td></tr>
+<tr><td>
+
+[HttpStorageService](./classes/HttpStorageService.md)
+
+</td><td>
+
+Service layer for storage API operations.
+
+</td></tr>
+</tbody></table>
+
+## Interfaces
+
+<table><thead><tr><th>
+
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[IStorageTreeItem](./interfaces/IStorageTreeItem.md)
+
+</td><td>
+
+Storage tree item metadata.
+
+</td></tr>
+<tr><td>
+
+[IStorageTreeChildrenResponse](./interfaces/IStorageTreeChildrenResponse.md)
+
+</td><td>
+
+Response for listing children.
+
+</td></tr>
+<tr><td>
+
+[IStorageFileResponse](./interfaces/IStorageFileResponse.md)
+
+</td><td>
+
+Response for reading a file.
+
+</td></tr>
+<tr><td>
+
+[IStoragePathRequest](./interfaces/IStoragePathRequest.md)
+
+</td><td>
+
+Request for path-based operations.
+
+</td></tr>
+<tr><td>
+
+[IStorageWriteFileRequest](./interfaces/IStorageWriteFileRequest.md)
+
+</td><td>
+
+Request for writing file contents.
+
+</td></tr>
+<tr><td>
+
+[IStorageSyncRequest](./interfaces/IStorageSyncRequest.md)
+
+</td><td>
+
+Request for sync operation.
+
+</td></tr>
+<tr><td>
+
+[IStorageSyncResponse](./interfaces/IStorageSyncResponse.md)
+
+</td><td>
+
+Sync response metadata.
+
+</td></tr>
+<tr><td>
+
+[IHttpStorageProvider](./interfaces/IHttpStorageProvider.md)
+
+</td><td>
+
+Provider contract for storage backends.
+
+</td></tr>
+<tr><td>
+
+[IHttpStorageProviderFactory](./interfaces/IHttpStorageProviderFactory.md)
+
+</td><td>
+
+Factory for creating namespace-scoped storage providers.
+
+</td></tr>
+<tr><td>
+
+[IFsStorageProviderFactoryOptions](./interfaces/IFsStorageProviderFactoryOptions.md)
+
+</td><td>
+
+Options for creating filesystem-backed storage providers.
+
+</td></tr>
+<tr><td>
+
+[ICreateStorageRoutesOptions](./interfaces/ICreateStorageRoutesOptions.md)
+
+</td><td>
+
+Options for creating storage routes.
+
+</td></tr>
+</tbody></table>
+
+## Type Aliases
+
+<table><thead><tr><th>
+
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[StorageNamespace](./type-aliases/StorageNamespace.md)
+
+</td><td>
+
+Namespace identifier for scoped storage.
+
+</td></tr>
+<tr><td>
+
+[StorageItemType](./type-aliases/StorageItemType.md)
+
+</td><td>
+
+Storage item type.
+
+</td></tr>
+</tbody></table>
+
+## Functions
+
+<table><thead><tr><th>
+
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[normalizeRequestPath](./functions/normalizeRequestPath.md)
+
+</td><td>
+
+Normalizes a request path to a consistent POSIX format.
+
+</td></tr>
+<tr><td>
+
+[sanitizeNamespace](./functions/sanitizeNamespace.md)
+
+</td><td>
+
+Sanitize namespace path segment.
+
+</td></tr>
+<tr><td>
+
+[createStorageRoutes](./functions/createStorageRoutes.md)
+
+</td><td>
+
+Builds storage routes for a Hono app.
+
+</td></tr>
+</tbody></table>
+
+## Variables
+
+<table><thead><tr><th>
+
+Name
+
+</th><th>
+
+Description
+
+</th></tr></thead>
+<tbody>
+<tr><td>
+
+[storageTreeItem](./variables/storageTreeItem.md)
+
+</td><td>
+
+Converter for IStorageTreeItem.
+
+</td></tr>
+<tr><td>
+
+[storagePathRequest](./variables/storagePathRequest.md)
+
+</td><td>
+
+Converter for path-based requests.
+
+</td></tr>
+<tr><td>
+
+[storageWriteFileRequest](./variables/storageWriteFileRequest.md)
+
+</td><td>
+
+Converter for write-file requests.
+
+</td></tr>
+<tr><td>
+
+[storageSyncRequest](./variables/storageSyncRequest.md)
+
+</td><td>
+
+Converter for sync requests.
+
+</td></tr>
+<tr><td>
+
+[storageFileResponse](./variables/storageFileResponse.md)
+
+</td><td>
+
+Converter for file responses.
+
+</td></tr>
+<tr><td>
+
+[storageTreeChildrenResponse](./variables/storageTreeChildrenResponse.md)
+
+</td><td>
+
+Converter for children list responses.
+
+</td></tr>
+</tbody></table>

package/docs/classes/FsStorageProvider.createDirectory.md

@@ -0,0 +1,20 @@
+[Home](../README.md) > [FsStorageProvider](./FsStorageProvider.md) > createDirectory
+
+## FsStorageProvider.createDirectory() method
+
+**Signature:**
+
+```typescript
+createDirectory(itemPath: string): Promise<Result<IStorageTreeItem>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>itemPath</td><td>string</td><td></td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;[IStorageTreeItem](../interfaces/IStorageTreeItem.md)&gt;&gt;

package/docs/classes/FsStorageProvider.getChildren.md

@@ -0,0 +1,20 @@
+[Home](../README.md) > [FsStorageProvider](./FsStorageProvider.md) > getChildren
+
+## FsStorageProvider.getChildren() method
+
+**Signature:**
+
+```typescript
+getChildren(itemPath: string): Promise<Result<readonly IStorageTreeItem[]>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>itemPath</td><td>string</td><td></td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;readonly [IStorageTreeItem](../interfaces/IStorageTreeItem.md)[]&gt;&gt;

package/docs/classes/FsStorageProvider.getFile.md

@@ -0,0 +1,20 @@
+[Home](../README.md) > [FsStorageProvider](./FsStorageProvider.md) > getFile
+
+## FsStorageProvider.getFile() method
+
+**Signature:**
+
+```typescript
+getFile(itemPath: string): Promise<Result<IStorageFileResponse>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>itemPath</td><td>string</td><td></td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;[IStorageFileResponse](../interfaces/IStorageFileResponse.md)&gt;&gt;

package/docs/classes/FsStorageProvider.getItem.md

@@ -0,0 +1,20 @@
+[Home](../README.md) > [FsStorageProvider](./FsStorageProvider.md) > getItem
+
+## FsStorageProvider.getItem() method
+
+**Signature:**
+
+```typescript
+getItem(itemPath: string): Promise<Result<IStorageTreeItem>>;
+```
+
+**Parameters:**
+
+<table><thead><tr><th>Parameter</th><th>Type</th><th>Description</th></tr></thead>
+<tbody>
+<tr><td>itemPath</td><td>string</td><td></td></tr>
+</tbody></table>
+
+**Returns:**
+
+Promise&lt;Result&lt;[IStorageTreeItem](../interfaces/IStorageTreeItem.md)&gt;&gt;