@toa.io/extensions.storages 1.0.0-alpha.292 → 1.0.0-alpha.293

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.storages",
-  "version": "1.0.0-alpha.292",
+  "version": "1.0.0-alpha.293",
   "type": "module",
   "description": "Toa Storages",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -17,22 +17,45 @@
   "publishConfig": {
     "access": "public"
   },
+  "files": [
+    "transpiled",
+    "readme.md",
+    "!**/tsconfig.tsbuildinfo",
+    "!**/*.test.*",
+    "!**/.env*"
+  ],
   "scripts": {
     "test": "echo \"Error: run tests from root\" && exit 1",
     "transpile": "npx tsc"
   },
   "devDependencies": {
+    "@aws-sdk/client-s3": "3.1125.0",
+    "@aws-sdk/lib-storage": "3.1125.0",
+    "cloudinary": "2.11.0",
     "dotenv": "17.4.2"
   },
-  "dependencies": {
+  "peerDependencies": {
     "@aws-sdk/client-s3": "3.1125.0",
     "@aws-sdk/lib-storage": "3.1125.0",
-    "@toa.io/definitions": "1.0.0-alpha.292",
+    "cloudinary": "2.11.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/lib-storage": {
+      "optional": true
+    },
+    "cloudinary": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@toa.io/definitions": "1.0.0-alpha.293",
     "@toa.io/generic": "1.0.0-alpha.292",
-    "@toa.io/schemas": "1.0.0-alpha.292",
-    "cloudinary": "2.11.0",
+    "@toa.io/schemas": "1.0.0-alpha.293",
     "negotiator": "1.1.0",
-    "openspan": "1.0.0-alpha.286"
+    "openspan": "1.0.0-alpha.293"
   },
-  "gitHead": "0f6aa3ad9dbec86bb632a7975ea61d1dde1d8fc5"
+  "gitHead": "1e05b3ab64758324c58c425f1f8e52e9f35f1da8"
 }

package/readme.md

@@ -2,6 +2,21 @@
 
 Shared BLOB storage.
 
+## Installing a provider
+
+A provider's SDK is not installed with this extension: `s3` and `spaces` need
+`@aws-sdk/client-s3` and `@aws-sdk/lib-storage`, `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.
+
+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:

package/transpiled/Factory.js

@@ -1,6 +1,6 @@
 import assert from 'node:assert';
 import { console } from 'openspan';
-import { providers } from './providers/index.js';
+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';
@@ -25,7 +25,7 @@ export class Factory {
     }
     async createStorage(name, declaration) {
         const { provider: id, ...options } = declaration;
-        const Provider = await providers[id]();
+        const Provider = await load(id);
         const secrets = this.resolveSecrets(name, Provider);
         const provider = new Provider(options, secrets);
         console.debug('Storage created', {

package/transpiled/Factory.js.map

@@ -1 +1 @@
-{"version":3,"file":"Factory.js","sourceRoot":"","sources":["../source/Factory.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"Factory.js","sourceRoot":"","sources":["../source/Factory.ts"],"names":[],"mappings":"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"}

package/transpiled/providers/index.d.ts

@@ -1,6 +1,9 @@
+import type { Constructor } from '../Provider.js';
 /**
  * A provider is loaded when a storage names it: the SDK one is written against is not paid
- * for by a process that declares another.
+ * for by a process that declares another, and is not installed by one either — it is an
+ * optional peer of this package, which a deploy installs for the storages a component
+ * declares. See `provider` below for what a workspace that has not gets told.
  */
 export declare const providers: {
     readonly s3: () => Promise<typeof import("./S3.js").S3>;
@@ -10,6 +13,9 @@ export declare const providers: {
     readonly tmp: () => Promise<typeof import("./Temporary.js").Temporary>;
     readonly test: () => Promise<typeof import("./Test.js").Test>;
 };
+export type Id = keyof typeof providers;
+/** The provider a declaration names, or what to install to have it. */
+export declare function provider(id: Id): Promise<Constructor>;
 export type { Declaration } from './Declaration.js';
 export type { S3Options } from './S3.js';
 export type { SpacesOptions } from './Spaces.js';

package/transpiled/providers/index.js

@@ -1,6 +1,9 @@
+import { packages } from '@toa.io/definitions/extensions.storages';
 /**
  * A provider is loaded when a storage names it: the SDK one is written against is not paid
- * for by a process that declares another.
+ * for by a process that declares another, and is not installed by one either — it is an
+ * optional peer of this package, which a deploy installs for the storages a component
+ * declares. See `provider` below for what a workspace that has not gets told.
  */
 export const providers = {
     s3: async () => (await import('./S3.js')).S3,
@@ -10,4 +13,20 @@ export const providers = {
     tmp: async () => (await import('./Temporary.js')).Temporary,
     test: async () => (await import('./Test.js')).Test
 };
+/** The provider a declaration names, or what to install to have it. */
+export async function provider(id) {
+    try {
+        return await providers[id]();
+    }
+    catch (error) {
+        const missing = Object.entries(packages[id]).map(([name, version]) => `${name}@${version}`);
+        if (missing.length === 0 || !isMissingModule(error))
+            throw error;
+        throw new Error(`Storage provider '${id}' needs ${missing.join(' ')}, which is not installed. ` +
+            `\`toa npm\` installs what this context's components declare.`, { cause: error });
+    }
+}
+function isMissingModule(error) {
+    return error?.code === 'ERR_MODULE_NOT_FOUND';
+}
 //# sourceMappingURL=index.js.map

package/transpiled/providers/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/providers/index.ts"],"names":[],"mappings":"AAEA;;;GAGG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,EAAE,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;IAC5C,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM;IACxD,UAAU,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,UAAU;IACpE,EAAE,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,UAAU;IAC5D,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS;IAC3D,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI;CACW,CAAA"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../source/providers/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,yCAAyC,CAAA;AAGlE;;;;;GAKG;AACH,MAAM,CAAC,MAAM,SAAS,GAAG;IACvB,EAAE,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,SAAS,CAAC,CAAC,CAAC,EAAE;IAC5C,MAAM,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,aAAa,CAAC,CAAC,CAAC,MAAM;IACxD,UAAU,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,UAAU;IACpE,EAAE,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,iBAAiB,CAAC,CAAC,CAAC,UAAU;IAC5D,GAAG,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,gBAAgB,CAAC,CAAC,CAAC,SAAS;IAC3D,IAAI,EAAE,KAAK,IAAI,EAAE,CAAC,CAAC,MAAM,MAAM,CAAC,WAAW,CAAC,CAAC,CAAC,IAAI;CACW,CAAA;AAI/D,uEAAuE;AACvE,MAAM,CAAC,KAAK,UAAU,QAAQ,CAAC,EAAM;IACnC,IAAI,CAAC;QACH,OAAO,MAAM,SAAS,CAAC,EAAE,CAAC,EAAE,CAAA;IAC9B,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,MAAM,OAAO,GAAG,MAAM,CAAC,OAAO,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,CAAC,GAAG,CAC9C,CAAC,CAAC,IAAI,EAAE,OAAO,CAAC,EAAE,EAAE,CAAC,GAAG,IAAI,IAAI,OAAO,EAAE,CAC1C,CAAA;QAED,IAAI,OAAO,CAAC,MAAM,KAAK,CAAC,IAAI,CAAC,eAAe,CAAC,KAAK,CAAC;YAAE,MAAM,KAAK,CAAA;QAEhE,MAAM,IAAI,KAAK,CACb,qBAAqB,EAAE,WAAW,OAAO,CAAC,IAAI,CAAC,GAAG,CAAC,4BAA4B;YAC7E,8DAA8D,EAChE,EAAE,KAAK,EAAE,KAAK,EAAE,CACjB,CAAA;IACH,CAAC;AACH,CAAC;AAED,SAAS,eAAe,CAAC,KAAc;IACrC,OAAQ,KAA2B,EAAE,IAAI,KAAK,sBAAsB,CAAA;AACtE,CAAC"}

package/CHANGELOG.md

@@ -1,34 +0,0 @@
-# Change Log
-
-All notable changes to this project will be documented in this file.
-See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
-
-# [1.0.0-alpha.292](https://github.com/toa-io/toa/compare/v1.0.0-alpha.291...v1.0.0-alpha.292) (2026-09-07)
-
-### Features
-
-* **definitions:** what a package declares is read from one package ([7052341](https://github.com/toa-io/toa/commit/70523411b5d9e2b204c999aa02365173f3bb518d))
-
-
-# [1.0.0-alpha.291](https://github.com/toa-io/toa/compare/v1.0.0-alpha.290...v1.0.0-alpha.291) (2026-09-07)
-
-**Note:** Version bump only for package @toa.io/extensions.storages
-
-
-
-
-
-# [1.0.0-alpha.289](https://github.com/toa-io/toa/compare/v1.0.0-alpha.288...v1.0.0-alpha.289) (2026-09-07)
-
-* A deploy moves only what changed, and a component sees none of the runtime's environment (#1073) ([f38e3db](https://github.com/toa-io/toa/commit/f38e3db533f24db866c57bfa1ef294eff1eaf499)), closes [#1073](https://github.com/toa-io/toa/issues/1073) [#1064](https://github.com/toa-io/toa/issues/1064) [#1066](https://github.com/toa-io/toa/issues/1066) [#1067](https://github.com/toa-io/toa/issues/1067) [#1068](https://github.com/toa-io/toa/issues/1068) [#1069](https://github.com/toa-io/toa/issues/1069) [#1071](https://github.com/toa-io/toa/issues/1071) [#1070](https://github.com/toa-io/toa/issues/1070) [#1072](https://github.com/toa-io/toa/issues/1072)
-
-### BREAKING CHANGES
-
-* a component that read `process.env.TOA_*` reads `context` instead;
-  `echo(input)` no longer substitutes from the environment; a bash operation sees no
-  `TOA_*`; images no longer set `USER node` — see migrations/289.md.
-
-
-# [1.0.0-alpha.287](https://github.com/toa-io/toa/compare/v1.0.0-alpha.286...v1.0.0-alpha.287) (2026-09-06)
-
-**Note:** Version bump only for package @toa.io/extensions.storages

package/source/Aspect.ts

@@ -1,32 +0,0 @@
-import assert from 'node:assert'
-import { Connector } from '@toa.io/core'
-import type { extensions } from '@toa.io/core/types'
-import { type Storage, type Storages } from './Storage.js'
-
-export class Aspect extends Connector implements extensions.Aspect {
-  public readonly name = 'storages'
-
-  private readonly create: () => Promise<Storages>
-  private storages: Storages = {}
-
-  /** The storages are made as the aspect connects: their providers load then, not before. */
-  public constructor(create: () => Promise<Storages>) {
-    super()
-
-    this.create = create
-  }
-
-  protected override async open(): Promise<void> {
-    this.storages = await this.create()
-  }
-
-  public invoke(name: string, method: keyof Storage, ...args: unknown[]): unknown {
-    const storage = this.storages[name]
-
-    assert.ok(storage !== undefined, `Storage '${name}' is not defined`)
-
-    // eslint-disable-next-line @typescript-eslint/ban-ts-comment
-    // @ts-expect-error
-    return storage[method](...args)
-  }
-}

package/source/Entry.ts

@@ -1,16 +0,0 @@
-import type { Readable } from 'node:stream'
-
-export type Entry = { id: string } & Metadata
-export type Stream = { stream: Readable } & Metadata
-
-export interface Metadata {
-  type: string
-  size: number | null
-  checksum: string
-  created: string
-  attributes: Attributes
-  range?: string
-  partial?: boolean
-}
-
-export type Attributes = Record<string, string>

package/source/Factory.ts

@@ -1,74 +0,0 @@
-import assert from 'node:assert'
-import { console } from 'openspan'
-import { providers } from './providers/index.js'
-import { Storage, type Storages } from './Storage.js'
-import { Aspect } from './Aspect.js'
-import { ENV_PREFIX, validateAnnotation } from '@toa.io/definitions/extensions.storages'
-import { environment } from '@toa.io/generic'
-import type { Constructor } from './Provider.js'
-import type { Declaration } from './providers/index.js'
-import type { Secrets } from './Secrets.js'
-import type { Annotation } from '@toa.io/definitions/extensions.storages'
-
-export class Factory {
-  private readonly annotation: Annotation
-
-  public constructor() {
-    const env = environment.get(ENV_PREFIX)
-
-    assert.ok(env !== undefined, `${ENV_PREFIX} is not defined`)
-
-    this.annotation = JSON.parse(env)
-
-    validateAnnotation(this.annotation)
-  }
-
-  public aspect(): Aspect {
-    return new Aspect(() => this.createStorages())
-  }
-
-  private async createStorages(): Promise<Storages> {
-    const storages: Storages = {}
-
-    for (const [name, declaration] of Object.entries(this.annotation))
-      // the annotation is validated above, so a declaration is its provider's
-      storages[name] = await this.createStorage(name, declaration as Declaration)
-
-    return storages
-  }
-
-  private async createStorage(name: string, declaration: Declaration): Promise<Storage> {
-    const { provider: id, ...options } = declaration
-    const Provider: Constructor = await providers[id]()
-    const secrets = this.resolveSecrets(name, Provider)
-    const provider = new Provider(options, secrets)
-
-    console.debug('Storage created', {
-      name,
-      provider: id,
-      ...(provider.root === undefined ? undefined : { root: provider.root })
-    })
-
-    return new Storage(provider, { name, provider: id })
-  }
-
-  private resolveSecrets(storageName: string, Class: Constructor): Secrets {
-    if (Class.SECRETS === undefined) return {}
-
-    const secrets: Record<string, string | undefined> = {}
-
-    for (const secret of Class.SECRETS) {
-      const variable = `${ENV_PREFIX}_${storageName}_${secret.name}`.toUpperCase()
-      const value = environment.get(variable)
-
-      assert.ok(
-        secret.optional === true || value !== undefined,
-        `'${variable}' is not defined`
-      )
-
-      secrets[secret.name] = value
-    }
-
-    return secrets
-  }
-}

package/source/Provider.ts

@@ -1,40 +0,0 @@
-import * as assert from 'node:assert'
-import type { Metadata, Stream } from './Entry.js'
-import type { Readable } from 'node:stream'
-import type { Maybe } from '@toa.io/core/types'
-import type { Secret, Secrets } from './Secrets.js'
-
-export abstract class Provider<Options = unknown> {
-  public static readonly SECRETS?: readonly Secret[]
-  public readonly root?: string
-  public readonly options: Options
-
-  protected constructor(options: Options, secrets?: Secrets) {
-    this.options = options
-
-    new.target.SECRETS?.forEach(({ name, optional }) =>
-      assert.ok(
-        optional === true || secrets?.[name] !== undefined,
-        `Missing secret '${name}'`
-      )
-    )
-  }
-
-  public abstract get(path: string, options?: unknown): Promise<Maybe<Stream>>
-
-  public abstract head(path: string): Promise<Maybe<Metadata>>
-
-  public abstract put(path: string, stream: Readable): Promise<void>
-
-  public abstract commit(path: string, metadata: Metadata): Promise<void>
-
-  public abstract delete(path: string): Promise<void>
-
-  public abstract move(from: string, to: string): Promise<Maybe<void>>
-}
-
-export interface Constructor<Options = any> {
-  SECRETS?: readonly Secret[]
-
-  new (options: Options, secrets?: Secrets): Provider<Options>
-}

package/source/Scanner.ts

@@ -1,170 +0,0 @@
-import { PassThrough, type TransformCallback } from 'node:stream'
-import { createHash } from 'node:crypto'
-import Negotiator from 'negotiator'
-
-export class Scanner extends PassThrough {
-  public size = 0
-  public type = 'application/octet-stream'
-  public error?: Error
-
-  private readonly hash = createHash('md5')
-  private readonly claim?: string
-  private readonly accept?: string
-  private readonly limit?: number
-  private position = 0
-  private completed = false
-  private readonly chunks: Buffer[] = []
-
-  public constructor(control?: ScanOptions) {
-    super()
-
-    this.claim = control?.claim
-    this.accept = control?.accept
-    this.limit = control?.limit
-  }
-
-  public digest(): string {
-    return this.hash.digest('hex')
-  }
-
-  public override _transform(
-    buffer: Buffer,
-    encoding: BufferEncoding,
-    callback: TransformCallback
-  ): void {
-    super._transform(buffer, encoding, callback)
-
-    this.process(buffer)
-  }
-
-  private readonly process = (buffer: Buffer): void => {
-    this.size += buffer.length
-    this.hash.update(buffer)
-
-    if (this.completed) return
-
-    if (this.position + buffer.length > HEADER_SIZE)
-      buffer = buffer.subarray(0, HEADER_SIZE - this.position)
-
-    this.chunks.push(buffer)
-    this.position += buffer.length
-
-    if (this.position === HEADER_SIZE) this.complete()
-
-    if (this.limit !== undefined && this.size > this.limit)
-      this.interrupt(ERR_LIMIT_EXCEEDED)
-  }
-
-  private complete(): void {
-    const header = Buffer.concat(this.chunks).toString('hex')
-
-    const signature = SIGNATURES.find(({ off, hex, expression }) => {
-      const sig = header.slice(off, off + hex.length)
-
-      return expression === undefined ? sig === hex : expression.test(sig)
-    })
-
-    const type = signature?.type ?? this.claim
-
-    if (type !== undefined) {
-      this.match(type)
-      this.type = type
-    }
-
-    this.verify(signature)
-    this.completed = true
-  }
-
-  private verify(signature: Signature | undefined): void {
-    if (this.claim === undefined || this.claim === 'application/octet-stream') return
-
-    const mismatch =
-      signature === undefined
-        ? KNOWN_TYPES.has(this.claim)
-        : this.claim !== signature.type
-
-    if (mismatch) this.interrupt(ERR_TYPE_MISMATCH)
-  }
-
-  private match(type: string): void {
-    if (this.accept === undefined) return
-
-    const unacceptable = this.negotiate(this.accept, [type]) === null
-
-    if (unacceptable) this.interrupt(ERR_NOT_ACCEPTABLE)
-  }
-
-  private negotiate(accept: string, type: string[]): string | null {
-    return new Negotiator({ headers: { accept } }).mediaType(type) ?? null
-  }
-
-  private interrupt(error: Error): void {
-    this.completed = true
-    this.error = error
-    this.destroy(error)
-  }
-}
-
-// https://en.wikipedia.org/wiki/List_of_file_signatures
-const SIGNATURES: Signature[] = [
-  { hex: 'ff d8 ff e0', off: 0, type: 'image/jpeg' },
-  { hex: 'ff d8 ff e1', off: 0, type: 'image/jpeg' },
-  { hex: 'ff d8 ff e2', off: 0, type: 'image/jpeg' },
-  { hex: 'ff d8 ff ee', off: 0, type: 'image/jpeg' },
-  { hex: 'ff d8 ff db', off: 0, type: 'image/jpeg' },
-  { hex: '89 50 4e 47', off: 0, type: 'image/png' },
-  { hex: '47 49 46 38', off: 0, type: 'image/gif' },
-  { hex: '52 49 46 46 ?? ?? ?? ?? 57 45 42 50', off: 0, type: 'image/webp' },
-  { hex: '4a 58 4c 20 0d 0a 87 0a', off: 8, type: 'image/jxl' },
-  { hex: '66 74 79 70 68 65 69 63', off: 8, type: 'image/heic' },
-  { hex: '66 74 79 70 61 76 69 66', off: 8, type: 'image/avif' },
-  { hex: '52 49 46 46 ?? ?? ?? ?? 41 56 49 20', off: 0, type: 'video/avi' },
-  { hex: '52 49 46 46 ?? ?? ?? ?? 57 41 56 45', off: 0, type: 'audio/wav' }
-  /*
-  When adding a new signature, include a copyright-free sample file in the `.tests` directory
-  and update the `signatures` test group in `Storage.test.ts`.
-   */
-].map((signature: Signature) => {
-  signature.hex = signature.hex.replaceAll(' ', '')
-
-  if (signature.hex.includes('??')) {
-    const expression = signature.hex.replaceAll(
-      /(?<wildcards>\?{1,24})/g,
-      (_, wildcards) => `[0-9a-f]{${wildcards.length}}`
-    )
-
-    signature.expression = new RegExp(expression, 'i')
-  }
-
-  return signature
-})
-
-const HEADER_SIZE =
-  SIGNATURES.reduce((max, { off, hex }) => Math.max(max, off + hex.length), 0) / 2
-
-const KNOWN_TYPES = new Set(SIGNATURES.map(({ type }) => type))
-
-const ERR_TYPE_MISMATCH = new (class TypeMismatchError extends Error {
-  public readonly code = 'TYPE_MISMATCH'
-})()
-
-const ERR_NOT_ACCEPTABLE = new (class NotAcceptableError extends Error {
-  public readonly code = 'NOT_ACCEPTABLE'
-})()
-
-const ERR_LIMIT_EXCEEDED = new (class LimitExceededError extends Error {
-  public readonly code = 'LIMIT_EXCEEDED'
-})()
-
-export interface ScanOptions {
-  claim?: string
-  accept?: string
-  limit?: number
-}
-
-interface Signature {
-  type: string
-  off: number
-  hex: string
-  expression?: RegExp
-}

package/source/Secrets.ts

@@ -1,6 +0,0 @@
-export type Secrets<K extends string = string> = Record<K | string, string | undefined>
-
-export interface Secret {
-  readonly name: string
-  readonly optional?: boolean
-}