@toa.io/extensions.storages 1.0.0-alpha.282 → 1.0.0-alpha.286

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toa.io/extensions.storages",
-  "version": "1.0.0-alpha.282",
+  "version": "1.0.0-alpha.286",
   "type": "module",
   "description": "Toa Storages",
   "author": "temich <tema.gurtovoy@gmail.com>",
@@ -27,10 +27,10 @@
   "dependencies": {
     "@aws-sdk/client-s3": "3.1125.0",
     "@aws-sdk/lib-storage": "3.1125.0",
-    "@toa.io/schemas": "1.0.0-alpha.282",
+    "@toa.io/schemas": "1.0.0-alpha.286",
     "cloudinary": "2.11.0",
     "negotiator": "1.1.0",
-    "openspan": "1.0.0-alpha.277"
+    "openspan": "1.0.0-alpha.286"
   },
-  "gitHead": "4007c814725dd015d3bbebb9a28e28a247645c4f"
+  "gitHead": "81f3d0688f17668b902be336d1749cc715edcdb6"
 }

package/readme.md

@@ -29,7 +29,7 @@ The Storages extension provides `storages` aspect,
 containing named Storage instances, according to the annotation.
 
 ```javascript
-async function effect (_, context) {
+async function effect(_, context) {
   await context.storages.photos.get('/path/to/b4f577e0.thumbnail.jpeg')
 }
 ```

package/source/Annotation.ts

@@ -6,7 +6,9 @@ import type { Schema } from '@toa.io/schemas'
 
 export type Annotation = Record<string, Declaration>
 
-export function validateAnnotation (annotation: unknown): asserts annotation is Annotation {
+export function validateAnnotation(
+  annotation: unknown
+): asserts annotation is Annotation {
   try {
     schemas.annotation.validate(annotation)
   } catch (error) {
@@ -20,19 +22,30 @@ export function validateAnnotation (annotation: unknown): asserts annotation is
 /*
 It is required because `oneOf` schema is used for the annotation validation.
  */
-function explain (annotation: unknown): void {
-  assert.ok(typeof annotation === 'object' && annotation !== null,
-    'TOA_STORAGES is not an object')
+function explain(annotation: unknown): void {
+  assert.ok(
+    typeof annotation === 'object' && annotation !== null,
+    'TOA_STORAGES is not an object'
+  )
 
   for (const declaration of Object.values(annotation)) {
-    assert.ok(typeof declaration === 'object' && declaration !== null &&
-      declaration.provider in providers,
-      `Unknown provider '${declaration.provider}'`)
-
-    assert.ok(declaration.provider in schemas,
-      `No schema for provider '${declaration.provider}'`)
-
-    const schema: Schema<Declaration> = schemas[declaration.provider as keyof typeof providers]
+    assert.ok(
+      typeof declaration === 'object' &&
+        declaration !== null &&
+        declaration.provider in providers,
+      `Unknown provider '${declaration.provider}'`
+    )
+
+    assert.ok(
+      declaration.provider in schemas,
+      `No schema for provider '${declaration.provider}'`
+    )
+
+    const provider = declaration.provider as keyof typeof providers
+
+    // the declaration names the provider
+    // oxlint-disable-next-line import/namespace
+    const schema: Schema<Declaration> = schemas[provider]
 
     schema.validate(declaration, `Storage '${declaration.provider}' annotation`)
   }

package/source/Aspect.ts

@@ -1,5 +1,6 @@
 import assert from 'node:assert'
-import { Connector, type extensions } from '@toa.io/core'
+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 {
@@ -7,13 +8,13 @@ export class Aspect extends Connector implements extensions.Aspect {
 
   private readonly storages: Storages
 
-  public constructor (storages: Storages) {
+  public constructor(storages: Storages) {
     super()
 
     this.storages = storages
   }
 
-  public invoke (name: string, method: keyof Storage, ...args: unknown[]): unknown {
+  public invoke(name: string, method: keyof Storage, ...args: unknown[]): unknown {
     const storage = this.storages[name]
 
     assert.ok(storage !== undefined, `Storage '${name}' is not defined`)

package/source/Factory.ts

@@ -13,7 +13,7 @@ import type { Secrets } from './Secrets.js'
 export class Factory {
   private readonly annotation: Annotation
 
-  public constructor () {
+  public constructor() {
     const env = process.env[ENV_PREFIX]
 
     assert.ok(env !== undefined, `${ENV_PREFIX} is not defined`)
@@ -23,13 +23,13 @@ export class Factory {
     validateAnnotation(this.annotation)
   }
 
-  public aspect (): Aspect {
+  public aspect(): Aspect {
     const storages = this.createStorages()
 
     return new Aspect(storages)
   }
 
-  private createStorages (): Storages {
+  private createStorages(): Storages {
     const storages: Storages = {}
 
     for (const [name, declaration] of Object.entries(this.annotation))
@@ -38,7 +38,7 @@ export class Factory {
     return storages
   }
 
-  private createStorage (name: string, declaration: Declaration): Storage {
+  private createStorage(name: string, declaration: Declaration): Storage {
     const { provider: id, ...options } = declaration
     const Provider: Constructor = providers[id]
     const secrets = this.resolveSecrets(name, Provider)
@@ -53,9 +53,8 @@ export class Factory {
     return new Storage(provider, { name, provider: id })
   }
 
-  private resolveSecrets (storageName: string, Class: Constructor): Secrets {
-    if (Class.SECRETS === undefined)
-      return {}
+  private resolveSecrets(storageName: string, Class: Constructor): Secrets {
+    if (Class.SECRETS === undefined) return {}
 
     const secrets: Record<string, string | undefined> = {}
 
@@ -63,8 +62,10 @@ export class Factory {
       const variable = `${ENV_PREFIX}_${storageName}_${secret.name}`.toUpperCase()
       const value = process.env[variable]
 
-      assert.ok(secret.optional === true || value !== undefined,
-        `'${variable}' is not defined`)
+      assert.ok(
+        secret.optional === true || value !== undefined,
+        `'${variable}' is not defined`
+      )
 
       secrets[secret.name] = value
     }

package/source/Provider.ts

@@ -1,7 +1,7 @@
 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/types'
+import type { Maybe } from '@toa.io/core/types'
 import type { Secret, Secrets } from './Secrets.js'
 
 export abstract class Provider<Options = unknown> {
@@ -9,24 +9,28 @@ export abstract class Provider<Options = unknown> {
   public readonly root?: string
   public readonly options: Options
 
-  protected constructor (options: Options, secrets?: Secrets) {
+  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}'`))
+      assert.ok(
+        optional === true || secrets?.[name] !== undefined,
+        `Missing secret '${name}'`
+      )
+    )
   }
 
-  public abstract get (path: string, options?: unknown): Promise<Maybe<Stream>>
+  public abstract get(path: string, options?: unknown): Promise<Maybe<Stream>>
 
-  public abstract head (path: string): Promise<Maybe<Metadata>>
+  public abstract head(path: string): Promise<Maybe<Metadata>>
 
-  public abstract put (path: string, stream: Readable): Promise<void>
+  public abstract put(path: string, stream: Readable): Promise<void>
 
-  public abstract commit (path: string, metadata: Metadata): Promise<void>
+  public abstract commit(path: string, metadata: Metadata): Promise<void>
 
-  public abstract delete (path: string): Promise<void>
+  public abstract delete(path: string): Promise<void>
 
-  public abstract move (from: string, to: string): Promise<Maybe<void>>
+  public abstract move(from: string, to: string): Promise<Maybe<void>>
 }
 
 export interface Constructor<Options = any> {

package/source/Scanner.ts

@@ -15,7 +15,7 @@ export class Scanner extends PassThrough {
   private completed = false
   private readonly chunks: Buffer[] = []
 
-  public constructor (control?: ScanOptions) {
+  public constructor(control?: ScanOptions) {
     super()
 
     this.claim = control?.claim
@@ -23,11 +23,15 @@ export class Scanner extends PassThrough {
     this.limit = control?.limit
   }
 
-  public digest (): string {
+  public digest(): string {
     return this.hash.digest('hex')
   }
 
-  public override _transform (buffer: Buffer, encoding: BufferEncoding, callback: TransformCallback): void {
+  public override _transform(
+    buffer: Buffer,
+    encoding: BufferEncoding,
+    callback: TransformCallback
+  ): void {
     super._transform(buffer, encoding, callback)
 
     this.process(buffer)
@@ -37,8 +41,7 @@ export class Scanner extends PassThrough {
     this.size += buffer.length
     this.hash.update(buffer)
 
-    if (this.completed)
-      return
+    if (this.completed) return
 
     if (this.position + buffer.length > HEADER_SIZE)
       buffer = buffer.subarray(0, HEADER_SIZE - this.position)
@@ -46,24 +49,20 @@ export class Scanner extends PassThrough {
     this.chunks.push(buffer)
     this.position += buffer.length
 
-    if (this.position === HEADER_SIZE)
-      this.complete()
+    if (this.position === HEADER_SIZE) this.complete()
 
     if (this.limit !== undefined && this.size > this.limit)
       this.interrupt(ERR_LIMIT_EXCEEDED)
   }
 
-  private complete (): void {
+  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)
+    const signature = SIGNATURES.find(({ off, hex, expression }) => {
+      const sig = header.slice(off, off + hex.length)
 
-        return expression === undefined
-          ? sig === hex
-          : expression.test(sig)
-      })
+      return expression === undefined ? sig === hex : expression.test(sig)
+    })
 
     const type = signature?.type ?? this.claim
 
@@ -76,33 +75,30 @@ export class Scanner extends PassThrough {
     this.completed = true
   }
 
-  private verify (signature: Signature | undefined): void {
-    if (this.claim === undefined || this.claim === 'application/octet-stream')
-      return
+  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
+    const mismatch =
+      signature === undefined
+        ? KNOWN_TYPES.has(this.claim)
+        : this.claim !== signature.type
 
-    if (mismatch)
-      this.interrupt(ERR_TYPE_MISMATCH)
+    if (mismatch) this.interrupt(ERR_TYPE_MISMATCH)
   }
 
-  private match (type: string): void {
-    if (this.accept === undefined)
-      return
+  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)
+    if (unacceptable) this.interrupt(ERR_NOT_ACCEPTABLE)
   }
 
-  private negotiate (accept: string, type: string[]): string | null {
+  private negotiate(accept: string, type: string[]): string | null {
     return new Negotiator({ headers: { accept } }).mediaType(type) ?? null
   }
 
-  private interrupt (error: Error): void {
+  private interrupt(error: Error): void {
     this.completed = true
     this.error = error
     this.destroy(error)
@@ -132,8 +128,10 @@ const SIGNATURES: 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}}`)
+    const expression = signature.hex.replaceAll(
+      /(?<wildcards>\?{1,24})/g,
+      (_, wildcards) => `[0-9a-f]{${wildcards.length}}`
+    )
 
     signature.expression = new RegExp(expression, 'i')
   }
@@ -141,8 +139,8 @@ const SIGNATURES: Signature[] = [
   return signature
 })
 
-const HEADER_SIZE = SIGNATURES
-  .reduce((max, { off, hex }) => Math.max(max, off + hex.length), 0) / 2
+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))
 

package/source/Storage.test.ts

@@ -41,7 +41,7 @@ describe('put', () => {
     const stream = createReadStream('lenna.png')
 
     startCreation = Date.now()
-    lenna = await storage.put(dir, stream) as Entry
+    lenna = (await storage.put(dir, stream)) as Entry
     path = `${dir}/${lenna.id}`
 
     assert(!(lenna instanceof Error))
@@ -76,7 +76,7 @@ describe('put', () => {
   })
 
   it('should create metadata', async () => {
-    const entry = await storage.head(path) as Entry
+    const entry = (await storage.head(path)) as Entry
 
     assert.partialDeepStrictEqual(entry, {
       type: 'image/png',
@@ -89,7 +89,7 @@ describe('put', () => {
 
   it('should set timestamp', async () => {
     const now = Date.now() + 1000 // Cloudinary has 1s resolution
-    const entry = await storage.get(path) as Stream
+    const entry = (await storage.get(path)) as Stream
     const created = new Date(entry.created).getTime()
 
     assert.ok(created <= now)
@@ -100,14 +100,13 @@ describe('put', () => {
     const stream = createReadStream('lenna.png')
     const id = Math.random().toString(36).slice(2)
 
-    const entry = await storage.put(dir, stream, { id }) as Entry
+    const entry = (await storage.put(dir, stream, { id })) as Entry
 
     assert.strictEqual(entry.id, id)
 
     const check = await storage.head(`${dir}/${id}`)
 
-    if (check instanceof Error)
-      throw check
+    if (check instanceof Error) throw check
 
     assert.strictEqual(check.id, id)
   })
@@ -120,13 +119,13 @@ describe('get, head', () => {
   beforeEach(async () => {
     const stream = createReadStream('lenna.png')
 
-    lenna = await storage.put(dir, stream) as Entry
+    lenna = (await storage.put(dir, stream)) as Entry
 
     path = `${dir}/${lenna.id}`
   })
 
   it('should get', async () => {
-    const entry = await storage.get(path) as Stream
+    const entry = (await storage.get(path)) as Stream
     const stored = await buffer(entry.stream)
     const buf = await buffer(createReadStream('lenna.png'))
 
@@ -134,26 +133,26 @@ describe('get, head', () => {
   })
 
   it('should get entry', async () => {
-    const entry = await storage.head(path) as Entry
+    const entry = (await storage.head(path)) as Entry
 
     assert.strictEqual(entry.id, lenna.id)
   })
 
   if (suite.provider === 'cloudinary') {
     it('should return cloudinary url', async () => {
-      const entry = await storage.head(`${path}.jpeg`) as Entry
+      const entry = (await storage.head(`${path}.jpeg`)) as Entry
 
       assert.match(entry.attributes.url, /^https:\/\//)
     })
 
     it('should support conditions', async () => {
-      const entry = await storage.head(`${path}.vertical.jpeg`) as Entry
+      const entry = (await storage.head(`${path}.vertical.jpeg`)) as Entry
 
       assert.strictEqual(entry.attributes.url.includes('/if_w_gt_h/a_90/if_end/'), true)
     })
 
     it('should return entry id when requested with extensions', async () => {
-      const entry = await storage.head(`${path}.jpeg`) as Entry
+      const entry = (await storage.head(`${path}.jpeg`)) as Entry
 
       assert.strictEqual(entry.id, lenna.id)
     })
@@ -166,7 +165,7 @@ describe('delete', () => {
   beforeEach(async () => {
     const stream = createReadStream('lenna.png')
 
-    lenna = await storage.put(dir, stream) as Entry
+    lenna = (await storage.put(dir, stream)) as Entry
   })
 
   it('should delete entry', async () => {
@@ -193,21 +192,21 @@ describe('signatures', () => {
   for (const type of ['jpeg', 'gif', 'webp', 'heic', 'jxl', 'avif'])
     it(`should detect image/${type}`, async () => {
       const stream = createReadStream('sample.' + type)
-      const entry = await storage.put(dir, stream) as Entry
+      const entry = (await storage.put(dir, stream)) as Entry
 
       assert.deepStrictEqual(entry['type'], 'image/' + type)
     })
 
   for (const type of ['avi'])
-     it(`should detect video/${type}`, async () => {
+    it(`should detect video/${type}`, async () => {
       const stream = createReadStream('sample.' + type)
-      const entry = await storage.put(dir, stream) as Entry
+      const entry = (await storage.put(dir, stream)) as Entry
 
       assert.deepStrictEqual(entry['type'], 'video/' + type)
     })
 
   for (const type of ['wav'])
-     it(`should detect audio/${type}`, async () => {
+    it(`should detect audio/${type}`, async () => {
       const stream = createReadStream('sample.' + type)
       const entry = (await storage.put(dir, stream)) as Entry
 
@@ -222,7 +221,7 @@ describe('signatures', () => {
   })
 })
 
-it('should return error if type doesn\'t match', async () => {
+it("should return error if type doesn't match", async () => {
   const stream = createReadStream('sample.jpeg')
 
   const result = await storage.put(dir, stream, { claim: 'image/png' })
@@ -278,7 +277,7 @@ it('should accept wildcard types', async () => {
 
 it('should handle root entries', async () => {
   const stream = createReadStream('sample.jpeg')
-  const result = await storage.put('/', stream) as Entry
+  const result = (await storage.put('/', stream)) as Entry
 
   assert.ok(!(result instanceof Error))
 
@@ -299,7 +298,7 @@ if (suite.provider !== 'cloudinary')
   it('should add origin attribute', async () => {
     const origin = 'https://example.com/image.jpeg'
     const stream = createReadStream('sample.jpeg')
-    const result = await storage.put('/origins', stream, { origin }) as Entry
+    const result = (await storage.put('/origins', stream, { origin })) as Entry
 
     assert.ok(!(result instanceof Error))
 

package/source/Storage.ts

@@ -11,16 +11,16 @@ export class Storage<T extends Provider = Provider> {
   private readonly provider: T
   private readonly scope?: Scope
 
-  public constructor (provider: T, scope?: Scope) {
+  public constructor(provider: T, scope?: Scope) {
     this.provider = provider
     this.scope = scope
   }
 
-  public options (): T['options'] {
+  public options(): T['options'] {
     return this.provider.options
   }
 
-  public async put (path: string, stream: Readable, options?: Options): Maybe<Entry> {
+  public async put(path: string, stream: Readable, options?: Options): Maybe<Entry> {
     return await console.span(this.span('put', path), async () => {
       const scanner = new Scanner(options)
       const pipe = stream.pipe(scanner).on('error', () => undefined)
@@ -31,14 +31,14 @@ export class Storage<T extends Provider = Provider> {
        * Provider can return or throw an error.
        * If thrown error is TYPE_MISMATCH from the Scanner, it should be returned.
        */
-      const error: Error | undefined = await this.provider.put(location, pipe)
+      const error: Error | undefined = await this.provider
+        .put(location, pipe)
         .catch((error: any) => {
           if (error === scanner.error) return error
           else throw error
         })
 
-      if (error instanceof Error)
-        return error
+      if (error instanceof Error) return error
 
       const metadata: Entry = {
         id,
@@ -49,8 +49,7 @@ export class Storage<T extends Provider = Provider> {
         attributes: options?.attributes ?? {}
       }
 
-      if (options?.origin !== undefined)
-        metadata.attributes.origin = options.origin
+      if (options?.origin !== undefined) metadata.attributes.origin = options.origin
 
       await this.provider.commit(location, metadata)
 
@@ -58,7 +57,7 @@ export class Storage<T extends Provider = Provider> {
     })
   }
 
-  public async get (path: string, options?: unknown): Maybe<Stream> {
+  public async get(path: string, options?: unknown): Maybe<Stream> {
     return await console.span(this.span('get', dirname(path)), async () => {
       const location = this.locate(path)
 
@@ -66,14 +65,13 @@ export class Storage<T extends Provider = Provider> {
     })
   }
 
-  public async head (path: string): Promise<Maybe<Entry>> {
+  public async head(path: string): Promise<Maybe<Entry>> {
     return await console.span(this.span('head', dirname(path)), async () => {
       const id = basename(path).split('.')[0]
       const location = this.locate(path)
       const metadata = await this.provider.head(location)
 
-      if (metadata instanceof Error)
-        return metadata
+      if (metadata instanceof Error) return metadata
 
       return {
         id,
@@ -82,7 +80,7 @@ export class Storage<T extends Provider = Provider> {
     })
   }
 
-  public async delete (path: string): Maybe<void> {
+  public async delete(path: string): Maybe<void> {
     return await console.span(this.span('delete', dirname(path)), async () => {
       const location = this.locate(path)
 
@@ -90,20 +88,20 @@ export class Storage<T extends Provider = Provider> {
     })
   }
 
-  public path (): string | null {
+  public path(): string | null {
     return this.provider.root ?? null
   }
 
-  private locate (...rel: string[]): string {
+  private locate(...rel: string[]): string {
     return join(ENTRIES, ...rel)
   }
 
-  private span (method: string, path: string): SpanOptions {
+  private span(method: string, path: string): SpanOptions {
     return {
       name: `${method} ${this.scope?.name ?? 'storage'}`,
       kind: 'client',
       attributes: {
-        ...this.scope === undefined ? {} : { provider: this.scope.provider },
+        ...(this.scope === undefined ? {} : { provider: this.scope.provider }),
         path
       }
     }

package/source/context.ts

@@ -0,0 +1,14 @@
+import type { Contribution } from '@toa.io/core/types'
+
+/** What this extension puts on the context of a component that declares it. */
+export function context(declaration: string[]): Contribution | null {
+  if (!Array.isArray(declaration) || declaration.length === 0) return null
+
+  const names = declaration.map((name) => JSON.stringify(name)).join(' | ')
+
+  return {
+    name: 'storages',
+    type: `Record<${names}, Storage>`,
+    imports: { '@toa.io/extensions.storages': ['Storage'] }
+  }
+}