@theshelf/filestore 0.0.1

package/README.md

@@ -0,0 +1,72 @@
+
+# File Store | The Shelf
+
+The file store package provides a universal interaction layer with an actual file storage solution.
+
+## Installation
+
+```bash
+npm install @theshelf/filestore
+```
+
+## Implementations
+
+Currently, there are two implementations:
+
+* **Memory** - non-persistent in memory storage (suited for testing).
+* **Minio** - persistent S3 compatible object storage.
+
+## Configuration
+
+The used implementation needs to be configured in the `.env` file.
+
+```env
+FILE_STORE_IMPLEMENTATION="minio" # (memory | minio)
+```
+
+In case of Minio, additional configuration is required.
+
+```env
+MINIO_END_POINT="address"
+MINIO_PORT_NUMBER=9000
+MINIO_USE_SSL=true
+MINIO_ACCESS_KEY="development"
+MINIO_SECRET_KEY="secret"
+```
+
+## How to use
+
+An instance of the configured file storage implementation can be imported for performing file operations.
+
+```ts
+import fileStorage from '@theshelf/filestorage';
+
+// Perform operations with the fileStorage instance
+```
+
+### Operations
+
+```ts
+import fileStorage from '@theshelf/filestorage';
+
+// Open connection
+await fileStorage.connect();
+
+// Close connection
+await fileStorage.disconnect();
+
+// Check if a file exists
+const exists: boolean = await fileStorage.hasFile('path/to/file.txt');
+
+// Write a file to the storage
+const data: Buffer = Buffer.from('Something interesting');
+await fileStorage.writeFile('path/to/file.txt', data);
+
+// Read a file from storage
+// Throws FileNotFound if not found
+const data: Buffer = await fileStorage.readFile('path/to/file.txt');
+
+// Delete a file from storage
+// Throws FileNotFound if not found
+await fileStorage.deleteFile('path/to/file.txt');
+```

package/dist/definitions/interfaces.d.ts

@@ -0,0 +1,10 @@
+export interface FileStore {
+    get connected(): boolean;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    hasFile(path: string): Promise<boolean>;
+    writeFile(path: string, data: Buffer): Promise<void>;
+    readFile(path: string): Promise<Buffer>;
+    deleteFile(path: string): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/definitions/interfaces.js

@@ -0,0 +1 @@
+export {};

package/dist/errors/FileNotFound.d.ts

@@ -0,0 +1,4 @@
+import FileSystemError from './FileSystemError';
+export default class FileNotFound extends FileSystemError {
+    constructor(path?: string);
+}

package/dist/errors/FileNotFound.js

@@ -0,0 +1,6 @@
+import FileSystemError from './FileSystemError';
+export default class FileNotFound extends FileSystemError {
+    constructor(path) {
+        super(path ? `File not found: ${path}` : 'File not found');
+    }
+}

package/dist/errors/FileSystemError.d.ts

@@ -0,0 +1,2 @@
+export default class FileSystemError extends Error {
+}

package/dist/errors/FileSystemError.js

@@ -0,0 +1,2 @@
+export default class FileSystemError extends Error {
+}

package/dist/errors/NotConnected.d.ts

@@ -0,0 +1,4 @@
+import FileSystemError from './FileSystemError';
+export default class NotConnected extends FileSystemError {
+    constructor(message?: string);
+}

package/dist/errors/NotConnected.js

@@ -0,0 +1,6 @@
+import FileSystemError from './FileSystemError';
+export default class NotConnected extends FileSystemError {
+    constructor(message) {
+        super(message ?? 'File system not connected');
+    }
+}

package/dist/errors/UnknownImplementation.d.ts

@@ -0,0 +1,4 @@
+import FileSystemError from './FileSystemError';
+export default class UnknownImplementation extends FileSystemError {
+    constructor(name: string);
+}

package/dist/errors/UnknownImplementation.js

@@ -0,0 +1,6 @@
+import FileSystemError from './FileSystemError';
+export default class UnknownImplementation extends FileSystemError {
+    constructor(name) {
+        super(`Unknown file system implementation: ${name}`);
+    }
+}

package/dist/implementation.d.ts

@@ -0,0 +1,3 @@
+import type { FileStore } from './definitions/interfaces';
+declare const _default: FileStore;
+export default _default;

package/dist/implementation.js

@@ -0,0 +1,14 @@
+import UnknownImplementation from './errors/UnknownImplementation';
+import createMemoryFS from './implementations/memory/create';
+import createMinioFS from './implementations/minio/create';
+const implementations = new Map([
+    ['memory', createMemoryFS],
+    ['minio', createMinioFS],
+]);
+const DEFAULT_FILE_STORE_IMPLEMENTATION = 'memory';
+const implementationName = process.env.FILE_STORE_IMPLEMENTATION ?? DEFAULT_FILE_STORE_IMPLEMENTATION;
+const creator = implementations.get(implementationName.toLowerCase());
+if (creator === undefined) {
+    throw new UnknownImplementation(implementationName);
+}
+export default creator();

package/dist/implementations/memory/Memory.d.ts

@@ -0,0 +1,12 @@
+import type { FileStore } from '../../definitions/interfaces';
+export default class Memory implements FileStore {
+    #private;
+    get connected(): boolean;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    hasFile(path: string): Promise<boolean>;
+    writeFile(path: string, data: Buffer): Promise<void>;
+    readFile(path: string): Promise<Buffer>;
+    deleteFile(path: string): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/implementations/memory/Memory.js

@@ -0,0 +1,45 @@
+import FileNotFound from '../../errors/FileNotFound';
+import NotConnected from '../../errors/NotConnected';
+export default class Memory {
+    #files = new Map();
+    #connected = false;
+    get connected() { return this.#connected; }
+    async connect() {
+        this.#connected = true;
+    }
+    async disconnect() {
+        this.#connected = false;
+    }
+    async hasFile(path) {
+        const files = this.#getFiles();
+        return files.has(path);
+    }
+    async writeFile(path, data) {
+        const files = this.#getFiles();
+        files.set(path, data);
+    }
+    async readFile(path) {
+        const files = this.#getFiles();
+        const data = files.get(path);
+        if (data === undefined) {
+            throw new FileNotFound(path);
+        }
+        return data;
+    }
+    async deleteFile(path) {
+        const files = this.#getFiles();
+        if (files.has(path) === false) {
+            throw new FileNotFound(path);
+        }
+        files.delete(path);
+    }
+    #getFiles() {
+        if (this.#files === undefined) {
+            throw new NotConnected();
+        }
+        return this.#files;
+    }
+    async clear() {
+        this.#files.clear();
+    }
+}

package/dist/implementations/memory/create.d.ts

@@ -0,0 +1,2 @@
+import Memory from './Memory';
+export default function create(): Memory;

package/dist/implementations/memory/create.js

@@ -0,0 +1,4 @@
+import Memory from './Memory';
+export default function create() {
+    return new Memory();
+}

package/dist/implementations/minio/MinioFS.d.ts

@@ -0,0 +1,14 @@
+import type { ClientOptions } from 'minio';
+import type { FileStore } from '../../definitions/interfaces';
+export default class MinioFS implements FileStore {
+    #private;
+    constructor(configuration: ClientOptions);
+    get connected(): boolean;
+    connect(): Promise<void>;
+    disconnect(): Promise<void>;
+    hasFile(path: string): Promise<boolean>;
+    writeFile(path: string, data: Buffer): Promise<void>;
+    readFile(path: string): Promise<Buffer>;
+    deleteFile(path: string): Promise<void>;
+    clear(): Promise<void>;
+}

package/dist/implementations/minio/MinioFS.js

@@ -0,0 +1,88 @@
+import { Client } from 'minio';
+import FileNotFound from '../../errors/FileNotFound';
+import NotConnected from '../../errors/NotConnected';
+const BUCKET_NAME = 'comify';
+export default class MinioFS {
+    #configuration;
+    #client;
+    constructor(configuration) {
+        this.#configuration = configuration;
+    }
+    get connected() {
+        return this.#client !== undefined;
+    }
+    async connect() {
+        this.#client = new Client(this.#configuration);
+        if (await this.#client.bucketExists(BUCKET_NAME) === false) {
+            await this.#client.makeBucket(BUCKET_NAME);
+        }
+    }
+    async disconnect() {
+        if (this.#client === undefined) {
+            throw new NotConnected();
+        }
+        this.#client = undefined;
+    }
+    async hasFile(path) {
+        const client = this.#getClient();
+        try {
+            await client.statObject(BUCKET_NAME, path);
+            return true;
+        }
+        catch (error) {
+            const customError = this.#handleError(error, path);
+            if (customError instanceof FileNotFound) {
+                return false;
+            }
+            throw error;
+        }
+    }
+    async writeFile(path, data) {
+        const client = this.#getClient();
+        try {
+            await client.putObject(BUCKET_NAME, path, data);
+        }
+        catch (error) {
+            throw this.#handleError(error, path);
+        }
+    }
+    async readFile(path) {
+        const client = this.#getClient();
+        try {
+            const stream = await client.getObject(BUCKET_NAME, path);
+            const chunks = await stream.toArray();
+            return Buffer.concat(chunks);
+        }
+        catch (error) {
+            throw this.#handleError(error, path);
+        }
+    }
+    async deleteFile(path) {
+        const client = this.#getClient();
+        try {
+            await client.removeObject(BUCKET_NAME, path);
+        }
+        catch (error) {
+            throw this.#handleError(error, path);
+        }
+    }
+    async clear() {
+        return; // Deliberately not implemented
+    }
+    #getClient() {
+        if (this.#client === undefined) {
+            throw new NotConnected();
+        }
+        return this.#client;
+    }
+    #handleError(error, path) {
+        if (error instanceof Error && this.#isNotFoundError(error)) {
+            return new FileNotFound(path);
+        }
+        return error;
+    }
+    #isNotFoundError(error) {
+        return error.message.startsWith('The specified key does not exist')
+            || error.message.startsWith('Not Found');
+    }
+}

package/dist/implementations/minio/create.d.ts

@@ -0,0 +1,2 @@
+import MinioFS from './MinioFS';
+export default function create(): MinioFS;

package/dist/implementations/minio/create.js

@@ -0,0 +1,9 @@
+import MinioFS from './MinioFS';
+export default function create() {
+    const endPoint = process.env.MINIO_END_POINT ?? 'undefined';
+    const port = Number(process.env.MINIO_PORT_NUMBER ?? 9000);
+    const useSSL = process.env.MINIO_USE_SSL === 'true';
+    const accessKey = process.env.MINIO_ROOT_USER ?? 'undefined';
+    const secretKey = process.env.MINIO_ROOT_PASSWORD ?? 'undefined';
+    return new MinioFS({ endPoint, port, useSSL, accessKey, secretKey });
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { FileStore } from './definitions/interfaces';
+export { default as FileNotFound } from './errors/FileNotFound';
+export { default as FileSystemError } from './errors/FileSystemError';
+export { default as NotConnected } from './errors/NotConnected';
+export { default as UnknownImplementation } from './errors/UnknownImplementation';
+export { default } from './implementation';

package/dist/index.js

@@ -0,0 +1,5 @@
+export { default as FileNotFound } from './errors/FileNotFound';
+export { default as FileSystemError } from './errors/FileSystemError';
+export { default as NotConnected } from './errors/NotConnected';
+export { default as UnknownImplementation } from './errors/UnknownImplementation';
+export { default } from './implementation';

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "@theshelf/filestore",
+  "private": false,
+  "version": "0.0.1",
+  "type": "module",
+  "scripts": {
+    "build": "tsc",
+    "clean": "rimraf dist",
+    "test": "vitest run",
+    "test-coverage": "vitest run --coverage",
+    "lint": "eslint",
+    "review": "npm run build && npm run lint && npm run test",
+    "prepublishOnly": "npm run clean && npm run build"
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "types": "dist/index.d.ts",
+  "exports": "./dist/index.js",
+  "dependencies": {
+    "minio": "8.0.6"
+  }
+}