@zenfs/core 0.1.0 → 0.2.0

package/dist/backends/backend.d.ts

@@ -1,17 +1,18 @@
-import type { TwoArgCallback, FileSystem } from '../filesystem.js';
+import { FileSystem } from '../filesystem.js';
+type OptionType = 'string' | 'number' | 'bigint' | 'boolean' | 'symbol' | 'undefined' | 'object' | 'function';
 /**
  * Describes a file system option.
  */
-export interface BackendOption<T> {
+export interface OptionConfig<T> {
     /**
      * The basic JavaScript type(s) for this option.
      */
-    type: string | string[];
+    type: OptionType | OptionType[];
     /**
-     * Whether or not the option is optional (e.g., can be set to null or undefined).
-     * Defaults to `false`.
+     * Whether or not the option is required (optional can be set to null or undefined).
+     * Defaults to false.
      */
-    optional?: boolean;
+    required?: boolean;
     /**
      * Description of the option. Used in error messages and documentation.
      */
@@ -26,22 +27,23 @@ export interface BackendOption<T> {
 /**
  * Describes all of the options available in a file system.
  */
-export interface BackendOptions {
-    [name: string]: BackendOption<unknown>;
-}
+type BackendOptionsConfig = Record<string, OptionConfig<unknown>>;
 /**
- * Contains types for static functions on a backend.
+ * A backend
  */
-export interface BaseBackendConstructor<FS extends typeof FileSystem = typeof FileSystem> {
-    new (...params: ConstructorParameters<FS>): InstanceType<FS>;
+export interface Backend<FS extends FileSystem = FileSystem, OC extends BackendOptionsConfig = BackendOptionsConfig> {
+    /**
+     * Create a new instance of the backend
+     */
+    create(options: object): FS;
     /**
      * A name to identify the backend.
      */
-    Name: string;
+    name: string;
     /**
      * Describes all of the options available for this backend.
      */
-    Options: BackendOptions;
+    options: OC;
     /**
      * Whether the backend is available in the current environment.
      * It supports checking synchronously and asynchronously
@@ -55,20 +57,34 @@ export interface BaseBackendConstructor<FS extends typeof FileSystem = typeof Fi
     isAvailable(): boolean;
 }
 /**
- * Contains types for static functions on a backend.
+ * @internal
  */
-export interface BackendConstructor<FS extends typeof FileSystem = typeof FileSystem> extends BaseBackendConstructor<FS> {
-    /**
-     * Creates backend of this given type with the given
-     * options, and either returns the result in a promise or callback.
-     */
-    Create(): Promise<InstanceType<FS>>;
-    Create(options: object): Promise<InstanceType<FS>>;
-    Create(cb: TwoArgCallback<InstanceType<FS>>): void;
-    Create(options: object, cb: TwoArgCallback<InstanceType<FS>>): void;
-    Create(options: object, cb?: TwoArgCallback<InstanceType<FS>>): Promise<InstanceType<FS>> | void;
+export declare function isBackend(arg: unknown): arg is Backend;
+/**
+ * Checks that the given options object is valid for the file system options.
+ * @internal
+ */
+export declare function checkOptions(backend: Backend, opts: object): Promise<void>;
+export declare function createBackend<B extends Backend>(backend: B, options?: object): Promise<ReturnType<B['create']>>;
+/**
+ * Specifies a file system backend type and its options.
+ *
+ * Individual options can recursively contain BackendConfig objects for
+ * option values that require file systems.
+ *
+ * The option object for each file system corresponds to that file system's option object passed to its `Create()` method.
+ */
+export interface BackendConfig {
+    backend: Backend;
+    [key: string]: unknown;
 }
-export declare function CreateBackend<FS extends BaseBackendConstructor>(this: FS): Promise<InstanceType<FS>>;
-export declare function CreateBackend<FS extends BaseBackendConstructor>(this: FS, options: BackendOptions): Promise<InstanceType<FS>>;
-export declare function CreateBackend<FS extends BaseBackendConstructor>(this: FS, cb: TwoArgCallback<InstanceType<FS>>): void;
-export declare function CreateBackend<FS extends BaseBackendConstructor>(this: FS, options: BackendOptions, cb: TwoArgCallback<InstanceType<FS>>): void;
+/**
+ * @internal
+ */
+export declare function isBackendConfig(arg: unknown): arg is BackendConfig;
+/**
+ * Retrieve a file system with the given configuration.
+ * @param config A BackendConfig object.
+ */
+export declare function resolveBackendConfig(options: BackendConfig): Promise<FileSystem>;
+export {};

package/dist/backends/backend.js

@@ -1,14 +1,84 @@
-import { checkOptions } from '../utils.js';
-export function CreateBackend(options, cb) {
-    cb = typeof options === 'function' ? options : cb;
-    checkOptions(this, options);
-    const fs = new this(typeof options === 'function' ? {} : options);
-    // Promise
-    if (typeof cb != 'function') {
-        return fs.whenReady();
-    }
-    // Callback
-    fs.whenReady()
-        .then(fs => cb(null, fs))
-        .catch(err => cb(err));
+import { ApiError, ErrorCode } from '../ApiError.js';
+import { levenshtein } from '../utils.js';
+/**
+ * @internal
+ */
+export function isBackend(arg) {
+    return arg != null && typeof arg == 'object' && 'isAvailable' in arg && typeof arg.isAvailable == 'function' && 'create' in arg && typeof arg.create == 'function';
+}
+/**
+ * Checks that the given options object is valid for the file system options.
+ * @internal
+ */
+export async function checkOptions(backend, opts) {
+    if (typeof opts != 'object' || opts === null) {
+        throw new ApiError(ErrorCode.EINVAL, 'Invalid options');
+    }
+    // Check for required options.
+    for (const [optName, opt] of Object.entries(backend.options)) {
+        const providedValue = opts && opt;
+        if (providedValue === undefined || providedValue === null) {
+            if (!opt.required) {
+                continue;
+            }
+            /* Required option not provided.
+            if any incorrect options provided, which ones are close to the provided one?
+            (edit distance 5 === close)*/
+            const incorrectOptions = Object.keys(opts)
+                .filter(o => !(o in backend.options))
+                .map((a) => {
+                return { str: a, distance: levenshtein(optName, a) };
+            })
+                .filter(o => o.distance < 5)
+                .sort((a, b) => a.distance - b.distance);
+            throw new ApiError(ErrorCode.EINVAL, `${backend.name}: Required option '${optName}' not provided.${incorrectOptions.length > 0 ? ` You provided '${incorrectOptions[0].str}', did you mean '${optName}'.` : ''}`);
+        }
+        // Option provided, check type.
+        const typeMatches = Array.isArray(opt.type) ? opt.type.indexOf(typeof providedValue) != -1 : typeof providedValue == opt.type;
+        if (!typeMatches) {
+            throw new ApiError(ErrorCode.EINVAL, `${backend.name}: Value provided for option ${optName} is not the proper type. Expected ${Array.isArray(opt.type) ? `one of {${opt.type.join(', ')}}` : opt.type}, but received ${typeof providedValue}\nOption description: ${opt.description}`);
+        }
+        if (opt.validator) {
+            await opt.validator(providedValue);
+        }
+        // Otherwise: All good!
+    }
+}
+export function createBackend(backend, options) {
+    checkOptions(backend, options);
+    const fs = backend.create(options);
+    return fs.ready();
+}
+/**
+ * @internal
+ */
+export function isBackendConfig(arg) {
+    return arg != null && typeof arg == 'object' && 'backend' in arg;
+}
+/**
+ * Retrieve a file system with the given configuration.
+ * @param config A BackendConfig object.
+ */
+export async function resolveBackendConfig(options) {
+    const { backend } = options;
+    if (!backend) {
+        throw new ApiError(ErrorCode.EPERM, 'Missing backend');
+    }
+    if (typeof options !== 'object' || options == null) {
+        throw new ApiError(ErrorCode.EINVAL, 'Invalid options on configuration object.');
+    }
+    const props = Object.keys(options).filter(k => k != 'backend');
+    for (const prop of props) {
+        let option = options[prop];
+        if (isBackend(option)) {
+            option = { backend: option };
+        }
+        if (isBackendConfig(option)) {
+            options[prop] = await resolveBackendConfig(option);
+        }
+    }
+    if (!backend) {
+        throw new ApiError(ErrorCode.EPERM, `Backend "${backend}" is not available`);
+    }
+    return backend.create(options);
 }

package/dist/backends/index.d.ts

@@ -1,11 +1,10 @@
 import { AsyncMirror } from './AsyncMirror.js';
-import { FolderAdapter } from './FolderAdapter.js';
-import { InMemoryFileSystem as InMemory } from './InMemory.js';
-import { OverlayFS } from './OverlayFS.js';
-import { BackendConstructor } from './backend.js';
+import { InMemory } from './InMemory.js';
+import { Overlay } from './OverlayFS.js';
+import { Backend } from './backend.js';
 export declare const backends: {
-    [backend: string]: BackendConstructor;
+    [backend: string]: Backend;
 };
 export default backends;
-export { AsyncMirror, FolderAdapter, InMemory, OverlayFS };
-export declare function registerBackend(..._backends: BackendConstructor[]): void;
+export { AsyncMirror, InMemory, Overlay };
+export declare function registerBackend(..._backends: Backend[]): void;

package/dist/backends/index.js

@@ -1,13 +1,12 @@
 import { AsyncMirror } from './AsyncMirror.js';
-import { FolderAdapter } from './FolderAdapter.js';
-import { InMemoryFileSystem as InMemory } from './InMemory.js';
-import { OverlayFS } from './OverlayFS.js';
+import { InMemory } from './InMemory.js';
+import { Overlay } from './OverlayFS.js';
 export const backends = {};
 export default backends;
-export { AsyncMirror, FolderAdapter, InMemory, OverlayFS };
+export { AsyncMirror, InMemory, Overlay };
 export function registerBackend(..._backends) {
     for (const backend of _backends) {
-        backends[backend.Name] = backend;
+        backends[backend.name] = backend;
     }
 }
-registerBackend(AsyncMirror, FolderAdapter, InMemory, OverlayFS);
+registerBackend(AsyncMirror, InMemory, Overlay);