@toa.io/extensions.storages 1.0.0-alpha.34 → 1.0.0-alpha.340

package/package.json

@@ -1,6 +1,7 @@
 {
   "name": "@toa.io/extensions.storages",
-  "version": "1.0.0-alpha.34",
+  "version": "1.0.0-alpha.340",
+  "type": "module",
   "description": "Toa Storages",
   "author": "temich <tema.gurtovoy@gmail.com>",
   "homepage": "https://github.com/toa-io/toa#readme",
@@ -16,27 +17,51 @@
   "publishConfig": {
     "access": "public"
   },
-  "jest": {
-    "preset": "ts-jest",
-    "testEnvironment": "node"
-  },
+  "files": [
+    "transpiled",
+    "readme.md",
+    "!**/tsconfig.tsbuildinfo",
+    "!**/*.test.*",
+    "!**/.env*"
+  ],
   "scripts": {
-    "test": "jest",
+    "test": "echo \"Error: run tests from root\" && exit 1",
     "transpile": "npx tsc"
   },
+  "devDependencies": {
+    "@aws-sdk/client-s3": "3.1156.0",
+    "@aws-sdk/lib-storage": "3.1156.0",
+    "@aws-sdk/s3-request-presigner": "3.1156.0",
+    "cloudinary": "2.11.0",
+    "dotenv": "18.0.9"
+  },
   "peerDependencies": {
-    "dotenv": "*"
+    "@aws-sdk/client-s3": "3.1156.0",
+    "@aws-sdk/lib-storage": "3.1156.0",
+    "@aws-sdk/s3-request-presigner": "3.1156.0",
+    "cloudinary": "2.11.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/lib-storage": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    },
+    "cloudinary": {
+      "optional": true
+    }
   },
   "dependencies": {
-    "@aws-sdk/client-s3": "3.481.0",
-    "@aws-sdk/lib-storage": "3.481.0",
-    "@toa.io/agent": "1.0.0-alpha.34",
-    "@toa.io/generic": "1.0.0-alpha.34",
-    "@toa.io/schemas": "1.0.0-alpha.34",
-    "error-value": "0.3.0",
-    "matchacho": "0.6.0",
-    "msgpackr": "1.10.1",
-    "smithy-node-native-fetch": "1.0.6"
-  },
-  "gitHead": "caf71c04ebd589ff54a25f533b975484aaf9a254"
+    "@toa.io/core": "1.0.0-alpha.333",
+    "@toa.io/definitions": "1.0.0-alpha.340",
+    "@toa.io/generic": "1.0.0-alpha.332",
+    "@toa.io/schemas": "1.0.0-alpha.332",
+    "negotiator": "1.1.0",
+    "openspan": "1.0.0-alpha.330"
+  },
+  "gitHead": "1871346ef431050d23bd8e91f2b920cea1aeb749"
 }

package/readme.md

@@ -2,19 +2,31 @@
 
 Shared BLOB storage.
 
+## Installing a provider
+
+A provider's SDK is not installed with this extension: `s3` and `spaces` need
+`@aws-sdk/client-s3`, `@aws-sdk/lib-storage` and `@aws-sdk/s3-request-presigner`, `cloudinary`
+needs `cloudinary`, and `fs`, `tmp` and `test` need nothing. A deploy installs what the components
+of each composition declare, so an image carries the SDK of a provider it uses and no other, and a
+process makes the storages its components declare — every one, for a component that names none.
+
+A workspace installs the same set itself, once, and again when a storage is added:
+
+```shell
+$ toa npm -p application
+```
+
+Without it a composition fails to start, naming the package and version it wants.
+
 ## Entry
 
 BLOBs are stored with the meta-information object (Entry) having the following properties:
 
-- `id` - checksum
-- `size` - size in bytes
-- `type` - MIME type
-- `created` - creation timestamp (UNIX time, ms)
-- `variants` - array of:
-  - `name` - unique name
-  - `size` - size in bytes
-  - `type` - variant MIME type
-- `meta` - object with application-specific information, empty by default
+- `size`: size in bytes
+- `type`: MIME type
+- `checksum`: content checksum
+- `created`: creation timestamp (ISO 8601)
+- `attributes`: `Record<string, string>` with application-specific information, empty by default
 
 ### Example
 
@@ -22,12 +34,7 @@ BLOBs are stored with the meta-information object (Entry) having the following p
 id: eecd837c
 type: image/jpeg
 created: 1698004822358
-variants:
-  - name: thumbnail.jpeg
-    type: image/jpeg
-  - name: thumbnail.webp
-    type: image/webp
-meta:
+attributes:
   face: true
   nudity: false
 ```
@@ -38,8 +45,8 @@ The Storages extension provides `storages` aspect,
 containing named Storage instances, according to the annotation.
 
 ```javascript
-async function effect (_, context) {
-  await context.storages.photos.fetch('/path/to/b4f577e0.thumbnail.jpeg')
+async function effect(_, context) {
+  await context.storages.photos.get('/path/to/b4f577e0.thumbnail.jpeg')
 }
 ```
 
@@ -47,13 +54,15 @@ async function effect (_, context) {
 
 > `Maybe<T> = T | Error`
 
+An error has a `code`, and an operation that returns it refuses with that code.
+
 #### `async put(path: string, stream: Readable, options?: Options): Maybe<Entry>`
 
-```
+```ts
 interface Options {
   claim?: string
   accept?: string
-  meta?: Record<string, string>
+  attributes?: Record<string, string>
 }
 ```
 
@@ -75,13 +84,13 @@ are: `image/jpeg`, `image/png`, `image/gif`, `image/webp`, `image/heic`, `image/
 
 See [source](source/Scanner.ts).
 
-#### `async get(path: string): Maybe<Entry>`
+#### `async head(path: string): Maybe<Entry>`
 
 Get an entry.
 
 If the entry does not exist, a `NOT_FOUND` error is returned.
 
-#### `async fetch(path: string): Maybe<Readable>`
+#### `async get(path: string): Maybe<Readable>`
 
 Fetch the BLOB specified by `path`. If the path does not exist, a `NOT_FOUND` error is returned.
 
@@ -91,6 +100,15 @@ Fetch the BLOB specified by `path`. If the path does not exist, a `NOT_FOUND` er
 - `/path/to/eecd837c` - fetch the BLOB by path
 - `/path/to/eecd837c.thumbnail.jpeg` - fetch the `thumbnail.jpeg` variant of the BLOB
 
+#### `async url(path: string, options?: { expires?: number }): Maybe<string>`
+
+Where the file is read straight from the provider, by whoever is given the address and with no
+credentials of their own. `s3` and `spaces` sign it for `expires` seconds — an hour by default, a
+week at most — and serve the file as the type it was stored as; `cloudinary` gives where it
+delivers the file, or a variant of it by extension, unsigned and without asking whether the file
+is there. `NOT_FOUND` is a file an `s3` or `spaces` storage does not have; `NO_URL` is a storage
+that serves no address of its own: `fs`, `tmp` and `test`.
+
 #### `async delete(path: string): Maybe<void>`
 
 Delete the entry specified by `path`.
@@ -110,18 +128,6 @@ await storage.move('/path/to/eecd837c', './sub/eecd837c')
 await storage.move('/path/to/eecd837c', './sub/')
 ```
 
-#### `async entries(path: string): Entry[]`
-
-Get a list of entries under the `path`.
-
-#### `async diversify(path: string, name: string, stream: Readable): Maybe<void>`
-
-Add or replace a `name` variant of the entry specified by `path`.
-
-#### `async annotate(path: string, key: string, value: any): Maybe<void>`
-
-Set a `key` property in the `meta` of the entry specified by `path`.
-
 ## Providers
 
 Storage uses underlying providers to store BLOBs and entries.
@@ -152,40 +158,114 @@ and [`toa env`](/runtime/cli/readme.md#env)
 for local environment.
 `endpoint` parameter is optional.
 
-### Filesystem
+### DigitalOcean Spaces
 
 Annotation format is:
 
 ```yaml
 storages:
-  photos@dev:
-    provider: fs
-    path: /var/my-storage
+  photos:
+    provider: spaces
+    space: my-space
+    region: fra1
 ```
 
-### Temporary
+`region` is the datacenter slug, the endpoint is derived from it.
 
-Filesystem using OS temporary directory.
+Secrets `ACCESS_KEY_ID` and `SECRET_ACCESS_KEY` are required.
+Keys are created in the DigitalOcean control panel,
+under Spaces Object Storage, on the Access Keys tab.
+
+### Cloudinary
+
+[Cloudinary](https://cloudinary.com) provider is used to store and transform media files.
+
+Objects stored in the Cloudinary storage can be requested with transformations,
+using dot-separated path extensions: `/path/to/eecd837c.{extension}.{extension}`.
+
+Transformation is defined by the `extension` property, which is a regular expression with named
+groups.
+The named groups are used to replace the placeholders in the `transform` object.
+
+`transform` object is an element of
+the [Cloudinary `transformation` array](https://cloudinary.com/documentation/node_image_manipulation#apply_common_image_transformations).
+
+> - `zoom` should be specified as integer [0–100].
+> - `format` value `jpeg` is converted to `jpg`.
+> - `^` and `$` are added to the regular expression automatically, unless they are already present.
 
 Annotation format is:
 
 ```yaml
 storages:
-  photos@dev:
-    provider: tmp
-    directory: my-app-tmp
+  media:
+    provider: cloudinary
+    environment: my-cloud
+    type: image # image or video
+    prefix: my-app
+    transformations:
+      - extension: (?<width>\d*)x(?<height>\d*)(z(?<zoom>\d*))?
+        transformation:
+          width: <width>
+          height: <height>
+          zoom: <zoom>
+          crop: thumb
+          gravity: face
+        optional: true
+      - extension: (?<format>jpeg|webp)
+        transformation:
+          fetch_format: <format>
+```
+
+Path extensions must be specified in the same order as in the annotation.
+
+For the example above:
+
+- `/path/to/eecd837c.100x100.jpeg`: matches
+- `/path/to/eecd837c.jpeg.100x100`: does not match
+
+If a path extension is not matched,
+or if at least one of the transformations is not matched (unless it is `optional`),
+then an error is returned.
+
+Secrets:
+
+- `API_KEY`
+- `API_SECRET`
+
+### Filesystem
+
+Annotation format is:
+
+```yaml
+storages:
+  photos:
+    provider: fs
+    path: /var/my-photos
 ```
 
-### Memory
+[Kubernetes PVC](https://kubernetes.io/docs/concepts/storage/persistent-volumes/) can be mounted to
+the storage:
 
-In-memory non-persistent storage.
+```yaml
+storages:
+  photos:
+    provider: fs
+    path: /var/my-photos
+    claim: photos-pvc
+```
 
-Annotation value format is:
+### Temporary
+
+Filesystem using OS temporary directory.
+
+Annotation format is:
 
 ```yaml
 storages:
   photos@dev:
-    provider: mem
+    provider: tmp
+    directory: my-app-tmp
 ```
 
 ## Deduplication
@@ -196,7 +276,7 @@ Variants, on the other hand, are not deduplicated across different entries.
 
 Underlying directory structure:
 
-```
+```text
 /temp
   c28f4dfd            # random id
 /blobs

package/transpiled/Aspect.d.ts

@@ -1,8 +1,12 @@
-import { Connector, type extensions } from '@toa.io/core';
-import { type Storage, type Storages } from './Storage';
+import { Connector } from '@toa.io/core';
+import type { extensions } from '@toa.io/core/types';
+import { type Storage, type Storages } from './Storage.ts';
 export declare class Aspect extends Connector implements extensions.Aspect {
     readonly name = "storages";
-    private readonly storages;
-    constructor(storages: Storages);
+    private readonly create;
+    private storages;
+    /** The storages are made as the aspect connects: their providers load then, not before. */
+    constructor(create: () => Promise<Storages>);
+    protected open(): Promise<void>;
     invoke(name: string, method: keyof Storage, ...args: unknown[]): unknown;
 }

package/transpiled/Aspect.js

@@ -1,25 +1,23 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Aspect = void 0;
-const node_assert_1 = __importDefault(require("node:assert"));
-const core_1 = require("@toa.io/core");
-class Aspect extends core_1.Connector {
+import { Connector } from '@toa.io/core';
+export class Aspect extends Connector {
     name = 'storages';
-    storages;
-    constructor(storages) {
+    create;
+    storages = {};
+    /** The storages are made as the aspect connects: their providers load then, not before. */
+    constructor(create) {
         super();
-        this.storages = storages;
+        this.create = create;
+    }
+    async open() {
+        this.storages = await this.create();
     }
     invoke(name, method, ...args) {
         const storage = this.storages[name];
-        node_assert_1.default.ok(storage !== undefined, `Storage '${name}' is not defined`);
+        if (storage === undefined)
+            throw new Error(`Storage '${name}' is not defined`);
         // eslint-disable-next-line @typescript-eslint/ban-ts-comment
         // @ts-expect-error
         return storage[method](...args);
     }
 }
-exports.Aspect = Aspect;
 //# sourceMappingURL=Aspect.js.map

package/transpiled/Aspect.js.map

@@ -1 +1 @@
-{"version":3,"file":"Aspect.js","sourceRoot":"","sources":["../source/Aspect.ts"],"names":[],"mappings":";;;;;;AAAA,8DAAgC;AAChC,uCAAyD;AAGzD,MAAa,MAAO,SAAQ,gBAAS;IACnB,IAAI,GAAG,UAAU,CAAA;IAEhB,QAAQ,CAAU;IAEnC,YAAoB,QAAkB;QACpC,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,QAAQ,GAAG,QAAQ,CAAA;IAC1B,CAAC;IAEM,MAAM,CAAE,IAAY,EAAE,MAAqB,EAAE,GAAG,IAAe;QACpE,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;QAEnC,qBAAM,CAAC,EAAE,CAAC,OAAO,KAAK,SAAS,EAAE,YAAY,IAAI,kBAAkB,CAAC,CAAA;QAEpE,6DAA6D;QAC7D,mBAAmB;QACnB,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACjC,CAAC;CACF;AApBD,wBAoBC"}
+{"version":3,"file":"Aspect.js","sourceRoot":"","sources":["../source/Aspect.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,cAAc,CAAA;AAIxC,MAAM,OAAO,MAAO,SAAQ,SAAS;IACnB,IAAI,GAAG,UAAU,CAAA;IAEhB,MAAM,CAAyB;IACxC,QAAQ,GAAa,EAAE,CAAA;IAE/B,2FAA2F;IAC3F,YAAmB,MAA+B;QAChD,KAAK,EAAE,CAAA;QAEP,IAAI,CAAC,MAAM,GAAG,MAAM,CAAA;IACtB,CAAC;IAEkB,KAAK,CAAC,IAAI;QAC3B,IAAI,CAAC,QAAQ,GAAG,MAAM,IAAI,CAAC,MAAM,EAAE,CAAA;IACrC,CAAC;IAEM,MAAM,CAAC,IAAY,EAAE,MAAqB,EAAE,GAAG,IAAe;QACnE,MAAM,OAAO,GAAG,IAAI,CAAC,QAAQ,CAAC,IAAI,CAAC,CAAA;QAEnC,IAAI,OAAO,KAAK,SAAS;YAAE,MAAM,IAAI,KAAK,CAAC,YAAY,IAAI,kBAAkB,CAAC,CAAA;QAE9E,6DAA6D;QAC7D,mBAAmB;QACnB,OAAO,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,CAAA;IACjC,CAAC;CACF"}

package/transpiled/Entry.d.ts

@@ -1,14 +1,17 @@
-export interface Entry {
+import type { Readable } from 'node:stream';
+export type Entry = {
     id: string;
-    size: number;
+} & Metadata;
+export type Stream = {
+    stream: Readable;
+} & Metadata;
+export interface Metadata {
     type: string;
-    created: number;
-    variants: Variant[];
-    meta: Record<string, unknown>;
+    size: number | null;
+    checksum: string;
+    created: string;
+    attributes: Attributes;
+    range?: string;
+    partial?: boolean;
 }
-interface Variant {
-    name: string;
-    size: number;
-    type: string;
-}
-export {};
+export type Attributes = Record<string, string>;

package/transpiled/Entry.js

@@ -1,3 +1,2 @@
-"use strict";
-Object.defineProperty(exports, "__esModule", { value: true });
+export {};
 //# sourceMappingURL=Entry.js.map

package/transpiled/Factory.d.ts

@@ -1,8 +1,16 @@
-import { Aspect } from './Aspect';
+import { Aspect } from './Aspect.ts';
 export declare class Factory {
     private readonly annotation;
+    /** The storages made so far, by name: one for the process, whichever component declares it. */
+    private readonly made;
     constructor();
-    aspect(): Aspect;
+    /**
+     * The storages of a component: those it declares, and every storage there is where it names
+     * none (`storages: ~`). A deploy installs the SDKs of the providers a composition's components
+     * declare and no other, so a storage nobody in the process declares is not made: its provider
+     * may not be there.
+     */
+    aspect(_: unknown, declaration?: string[] | null): Aspect;
     private createStorages;
     private createStorage;
     private resolveSecrets;

package/transpiled/Factory.js

@@ -1,53 +1,73 @@
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-exports.Factory = void 0;
-const node_assert_1 = __importDefault(require("node:assert"));
-const generic_1 = require("@toa.io/generic");
-const providers_1 = require("./providers");
-const Storage_1 = require("./Storage");
-const Aspect_1 = require("./Aspect");
-const deployment_1 = require("./deployment");
-const Annotation_1 = require("./Annotation");
-class Factory {
+import { console } from 'openspan';
+import { provider as load } from './providers/index.js';
+import { Storage } from './Storage.js';
+import { Aspect } from './Aspect.js';
+import { ENV_PREFIX, validateAnnotation } from '@toa.io/definitions/extensions.storages';
+import { environment } from '@toa.io/generic';
+export class Factory {
     annotation;
+    /** The storages made so far, by name: one for the process, whichever component declares it. */
+    made = new Map();
     constructor() {
-        const env = process.env.TOA_STORAGES;
-        node_assert_1.default.ok(env !== undefined, 'TOA_STORAGES is not defined');
-        this.annotation = (0, generic_1.decode)(env);
-        (0, Annotation_1.validateAnnotation)(this.annotation);
+        const env = environment.get(ENV_PREFIX);
+        if (env === undefined)
+            throw new Error(`${ENV_PREFIX} is not defined`);
+        this.annotation = JSON.parse(env);
+        validateAnnotation(this.annotation);
     }
-    aspect() {
-        const storages = this.createStorages();
-        return new Aspect_1.Aspect(storages);
+    /**
+     * The storages of a component: those it declares, and every storage there is where it names
+     * none (`storages: ~`). A deploy installs the SDKs of the providers a composition's components
+     * declare and no other, so a storage nobody in the process declares is not made: its provider
+     * may not be there.
+     */
+    aspect(_, declaration) {
+        const names = declaration === undefined || declaration === null || declaration.length === 0
+            ? Object.keys(this.annotation)
+            : declaration;
+        return new Aspect(() => this.createStorages(names));
     }
-    createStorages() {
+    async createStorages(names) {
         const storages = {};
-        for (const [name, declaration] of Object.entries(this.annotation))
-            storages[name] = this.createStorage(name, declaration);
+        for (const name of names) {
+            const declaration = this.annotation[name];
+            // one the annotation does not declare is refused as it is used (`Aspect.invoke`)
+            if (declaration === undefined)
+                continue;
+            let storage = this.made.get(name);
+            if (storage === undefined) {
+                // the annotation is validated above, so a declaration is its provider's
+                storage = this.createStorage(name, declaration);
+                this.made.set(name, storage);
+            }
+            storages[name] = await storage;
+        }
         return storages;
     }
-    createStorage(name, declaration) {
-        const { provider: providerId, ...options } = declaration;
-        const Provider = providers_1.providers[providerId];
+    async createStorage(name, declaration) {
+        const { provider: id, ...options } = declaration;
+        const Provider = await load(id);
         const secrets = this.resolveSecrets(name, Provider);
         const provider = new Provider(options, secrets);
-        return new Storage_1.Storage(provider);
+        console.debug('Storage created', {
+            name,
+            provider: id,
+            ...(provider.root === undefined ? undefined : { root: provider.root })
+        });
+        return new Storage(provider, { name, provider: id });
     }
     resolveSecrets(storageName, Class) {
         if (Class.SECRETS === undefined)
             return {};
         const secrets = {};
         for (const secret of Class.SECRETS) {
-            const variable = `${deployment_1.SERIALIZATION_PREFIX}_${storageName}_${secret.name}`.toUpperCase();
-            const value = process.env[variable];
-            node_assert_1.default.ok(secret.optional === true || value !== undefined, `'${variable}' is not defined`);
+            const variable = `${ENV_PREFIX}_${storageName}_${secret.name}`.toUpperCase();
+            const value = environment.get(variable);
+            if (secret.optional !== true && value === undefined)
+                throw new Error(`'${variable}' is not defined`);
             secrets[secret.name] = value;
         }
         return secrets;
     }
 }
-exports.Factory = Factory;
 //# sourceMappingURL=Factory.js.map

package/transpiled/Factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"Factory.js","sourceRoot":"","sources":["../source/Factory.ts"],"names":[],"mappings":";;;;;;AAAA,8DAAgC;AAChC,6CAAwC;AACxC,2CAAuC;AACvC,uCAAkD;AAClD,qCAAiC;AACjC,6CAAmD;AACnD,6CAAiD;AAKjD,MAAa,OAAO;IACD,UAAU,CAAY;IAEvC;QACE,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,CAAC,YAAY,CAAA;QAEpC,qBAAM,CAAC,EAAE,CAAC,GAAG,KAAK,SAAS,EAAE,6BAA6B,CAAC,CAAA;QAE3D,IAAI,CAAC,UAAU,GAAG,IAAA,gBAAM,EAAC,GAAG,CAAC,CAAA;QAE7B,IAAA,+BAAkB,EAAC,IAAI,CAAC,UAAU,CAAC,CAAA;IACrC,CAAC;IAEM,MAAM;QACX,MAAM,QAAQ,GAAG,IAAI,CAAC,cAAc,EAAE,CAAA;QAEtC,OAAO,IAAI,eAAM,CAAC,QAAQ,CAAC,CAAA;IAC7B,CAAC;IAEO,cAAc;QACpB,MAAM,QAAQ,GAAa,EAAE,CAAA;QAE7B,KAAK,MAAM,CAAC,IAAI,EAAE,WAAW,CAAC,IAAI,MAAM,CAAC,OAAO,CAAC,IAAI,CAAC,UAAU,CAAC;YAC/D,QAAQ,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC,aAAa,CAAC,IAAI,EAAE,WAAW,CAAC,CAAA;QAExD,OAAO,QAAQ,CAAA;IACjB,CAAC;IAEO,aAAa,CAAE,IAAY,EAAE,WAAwB;QAC3D,MAAM,EAAE,QAAQ,EAAE,UAAU,EAAE,GAAG,OAAO,EAAE,GAAG,WAAW,CAAA;QACxD,MAAM,QAAQ,GAAwB,qBAAS,CAAC,UAAU,CAAC,CAAA;QAC3D,MAAM,OAAO,GAAG,IAAI,CAAC,cAAc,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAA;QACnD,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,OAAO,EAAE,OAAO,CAAC,CAAA;QAE/C,OAAO,IAAI,iBAAO,CAAC,QAAQ,CAAC,CAAA;IAC9B,CAAC;IAEO,cAAc,CAAE,WAAmB,EACzC,KAA0B;QAC1B,IAAI,KAAK,CAAC,OAAO,KAAK,SAAS;YAC7B,OAAO,EAAE,CAAA;QAEX,MAAM,OAAO,GAAuC,EAAE,CAAA;QAEtD,KAAK,MAAM,MAAM,IAAI,KAAK,CAAC,OAAO,EAAE,CAAC;YACnC,MAAM,QAAQ,GAAG,GAAG,iCAAoB,IAAI,WAAW,IAAI,MAAM,CAAC,IAAI,EAAE,CAAC,WAAW,EAAE,CAAA;YACtF,MAAM,KAAK,GAAG,OAAO,CAAC,GAAG,CAAC,QAAQ,CAAC,CAAA;YAEnC,qBAAM,CAAC,EAAE,CAAC,MAAM,CAAC,QAAQ,KAAK,IAAI,IAAI,KAAK,KAAK,SAAS,EACvD,IAAI,QAAQ,kBAAkB,CAAC,CAAA;YAEjC,OAAO,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,KAAK,CAAA;QAC9B,CAAC;QAED,OAAO,OAAO,CAAA;IAChB,CAAC;CACF;AAxDD,0BAwDC"}
+{"version":3,"file":"Factory.js","sourceRoot":"","sources":["../source/Factory.ts"],"names":[],"mappings":"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"}

package/transpiled/Provider.d.ts

@@ -1,22 +1,26 @@
-/// <reference types="node" />
-import { type Readable } from 'node:stream';
-export type ProviderSecrets<K extends string = string> = Record<K | string, string | undefined>;
-export interface ProviderSecret {
-    readonly name: string;
-    readonly optional?: boolean;
-}
-export declare abstract class Provider<Options = void> {
-    static readonly SECRETS: readonly ProviderSecret[];
-    constructor(_: Options, secrets?: ProviderSecrets);
-    abstract get(path: string): Promise<Readable | null>;
-    abstract list(path: string): Promise<string[]>;
-    abstract put(path: string, filename: string, stream: Readable): Promise<void>;
+import type { Metadata, Stream } from './Entry.ts';
+import type { Readable } from 'node:stream';
+import type { Maybe } from '@toa.io/core/types';
+import type { Secret, Secrets } from './Secrets.ts';
+export declare abstract class Provider<Options = unknown> {
+    static readonly SECRETS?: readonly Secret[];
+    readonly root?: string;
+    readonly options: Options;
+    protected constructor(options: Options, secrets?: Secrets);
+    abstract get(path: string, options?: unknown): Promise<Maybe<Stream>>;
+    abstract head(path: string): Promise<Maybe<Metadata>>;
+    abstract put(path: string, stream: Readable): Promise<void>;
+    abstract commit(path: string, metadata: Metadata): Promise<void>;
     abstract delete(path: string): Promise<void>;
-    abstract move(from: string, to: string): Promise<void>;
-    abstract moveDir(from: string, to: string): Promise<void>;
+    abstract move(from: string, to: string): Promise<Maybe<void>>;
+    /**
+     * Where whoever is given it reads the file straight from the provider, with no credentials of
+     * their own, for `expires` seconds where the address is signed. A provider that serves no
+     * address of its own answers `NO_URL`.
+     */
+    url(_path: string, _expires: number): Promise<Maybe<string>>;
 }
-export interface ProviderConstructor {
-    readonly SECRETS: readonly ProviderSecret[];
-    prototype: Provider;
-    new (options: any, secrets?: ProviderSecrets): Provider;
+export interface Constructor<Options = any> {
+    SECRETS?: readonly Secret[];
+    new (options: Options, secrets?: Secrets): Provider<Options>;
 }