@toa.io/extensions.storages 1.0.0-alpha.0 → 1.0.0-alpha.2

package/source/schemas.test.ts

@@ -0,0 +1,58 @@
+import * as schemas from './schemas'
+
+const ok = {
+  a: {
+    provider: 'tmp',
+    directory: 'ok'
+  },
+  b: {
+    provider: 'fs',
+    path: 'ok'
+  },
+  c: {
+    provider: 's3',
+    bucket: 'my-bucket'
+  },
+  d: {
+    provider: 'mem'
+  }
+}
+
+const oh = [
+  {
+    whatever: {
+      provider: 'non-existent'
+    }
+  },
+  {
+    whatever: {
+      provider: 'fs'
+    }
+  },
+  {
+    whatever: {
+      provider: 'tmp',
+      extra: true
+    }
+  },
+  {
+    whatever: {
+
+      provider: 's3'
+    }
+  },
+  {
+    whatever: {
+      provider: 'mem',
+      extra: true
+    }
+  }
+]
+
+it('should pass', () => {
+  expect(() => schemas.annotation.validate(ok)).not.toThrow()
+})
+
+it.each(oh)('should fail', (value) => {
+  expect(() => schemas.annotation.validate(value)).toThrow()
+})

package/source/schemas.ts

@@ -0,0 +1,15 @@
+import { resolve } from 'node:path'
+import { namespace } from '@toa.io/schemas'
+import type { Declaration } from './providers'
+import type { Schema } from '@toa.io/schemas'
+import type { Annotation } from './Annotation'
+
+const path = resolve(__dirname, '../schemas')
+const ns = namespace(path)
+
+export const annotation: Schema<Annotation> = ns.schema<Annotation>('annotation')
+export const s3: Schema<Declaration> = ns.schema<Declaration>('s3')
+export const fs: Schema<Declaration> = ns.schema<Declaration>('fs')
+export const mem: Schema<Declaration> = ns.schema<Declaration>('mem')
+export const tmp: Schema<Declaration> = ns.schema<Declaration>('tmp')
+export const test: Schema<Declaration> = ns.schema<Declaration>('test')

package/source/test/util.ts

@@ -1,74 +1,45 @@
 import { join } from 'node:path'
-import fs from 'node:fs/promises'
-import { createReadStream, type ReadStream } from 'node:fs'
-import { CreateBucketCommand, S3Client } from '@aws-sdk/client-s3'
 import dotenv from 'dotenv'
+import type { ProviderSecrets } from '../Provider'
+import type { providers } from '../providers'
+import type { FileSystemOptions } from '../providers/FileSystem'
+import type { S3Options } from '../providers/S3'
+import type { TemporaryOptions } from '../providers/Temporary'
 
 dotenv.config({ path: join(__dirname, '.env') })
 
-const suites: Suite[] = [
+export const suites = [
   {
     run: true,
-    ref: 'tmp:///toa-storages-temp'
+    provider: 'tmp',
+    options: {
+      directory: 'toa-storages-temp'
+    }
+  },
+  {
+    run: true,
+    provider: 'mem'
   },
   {
     run: process.env.RUN_S3 === '1',
-    ref: 's3://us-west-1/test-bucket?endpoint=http://s3.localhost.localstack.cloud:4566',
+    provider: 's3',
+    options: {
+      endpoint: 'http://localhost:4566',
+      region: 'us-west-1',
+      bucket: 'test-bucket'
+    },
     secrets: {
       ACCESS_KEY_ID: 'developer',
       SECRET_ACCESS_KEY: 'secret'
-    },
-    init: initS3
+    }
   }
   // add more providers here, use `run` as a condition to run the test
   // e.g.: `run: process.env.ACCESS_KEY_ID !== undefined`
-]
-
-function map (suite: Suite): Case {
-  const url = new URL(suite.ref)
-
-  return [url.protocol, url, suite.secrets ?? {}, suite.init]
-}
-
-export const cases = suites.filter(({ run }) => run).map(map)
-
-export function rnd (): string {
-  return Math.random().toString(36).slice(2)
-}
-
-export function open (rel: string): ReadStream {
-  const path = join(__dirname, rel)
-
-  return createReadStream(path)
-}
-
-export async function read (rel: string): Promise<Buffer> {
-  const path = join(__dirname, rel)
-
-  return await fs.readFile(path)
-}
-
-async function initS3 (url: URL, secrets: Record<string, string>): Promise<void> {
-  const client = new S3Client({
-    credentials: {
-      accessKeyId: secrets.ACCESS_KEY_ID,
-      secretAccessKey: secrets.SECRET_ACCESS_KEY
-    },
-    region: url.host,
-    endpoint: url.searchParams.get('endpoint') ?? undefined
-  })
-
-  const command = new CreateBucketCommand({ Bucket: url.pathname.substring(1) })
-
-  await client.send(command).catch(() => undefined)
-}
+] satisfies Suite[]
 
 interface Suite {
   run: boolean
-  ref: string
-  secrets?: Record<string, string>
-  init?: SuiteInit
+  provider: keyof typeof providers
+  options?: FileSystemOptions | S3Options | TemporaryOptions
+  secrets?: ProviderSecrets
 }
-
-type SuiteInit = (url: URL, secrets: Record<string, string>) => Promise<void> | void
-type Case = [string, URL, Record<string, string>, SuiteInit?]

package/transpiled/Annotation.d.ts

@@ -0,0 +1,3 @@
+import type { Declaration } from './providers';
+export type Annotation = Record<string, Declaration>;
+export declare function validateAnnotation(annotation: unknown): asserts annotation is Annotation;

package/transpiled/Annotation.js

@@ -0,0 +1,57 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.validateAnnotation = void 0;
+const node_assert_1 = __importDefault(require("node:assert"));
+const providers_1 = require("./providers");
+const schemas = __importStar(require("./schemas"));
+function validateAnnotation(annotation) {
+    try {
+        schemas.annotation.validate(annotation);
+    }
+    catch (error) {
+        explain(annotation);
+        // if all declarations are valid, re-throw the error
+        throw error;
+    }
+}
+exports.validateAnnotation = validateAnnotation;
+/*
+It is required because `oneOf` schema is used for the annotation validation.
+ */
+function explain(annotation) {
+    node_assert_1.default.ok(typeof annotation === 'object' && annotation !== null, 'TOA_STORAGES is not an object');
+    for (const declaration of Object.values(annotation)) {
+        node_assert_1.default.ok(typeof declaration === 'object' && declaration !== null &&
+            declaration.provider in providers_1.providers, `Unknown provider '${declaration.provider}'`);
+        node_assert_1.default.ok(declaration.provider in schemas, `No schema for provider '${declaration.provider}'`);
+        const schema = schemas[declaration.provider];
+        schema.validate(declaration, `Storage '${declaration.provider}' annotation`);
+    }
+}
+//# sourceMappingURL=Annotation.js.map

package/transpiled/Annotation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Annotation.js","sourceRoot":"","sources":["../source/Annotation.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAAA,8DAAgC;AAChC,2CAAuC;AACvC,mDAAoC;AAMpC,SAAgB,kBAAkB,CAAE,UAAmB;IACrD,IAAI,CAAC;QACH,OAAO,CAAC,UAAU,CAAC,QAAQ,CAAC,UAAU,CAAC,CAAA;IACzC,CAAC;IAAC,OAAO,KAAK,EAAE,CAAC;QACf,OAAO,CAAC,UAAU,CAAC,CAAA;QAEnB,oDAAoD;QACpD,MAAM,KAAK,CAAA;IACb,CAAC;AACH,CAAC;AATD,gDASC;AAED;;GAEG;AACH,SAAS,OAAO,CAAE,UAAmB;IACnC,qBAAM,CAAC,EAAE,CAAC,OAAO,UAAU,KAAK,QAAQ,IAAI,UAAU,KAAK,IAAI,EAC7D,+BAA+B,CAAC,CAAA;IAElC,KAAK,MAAM,WAAW,IAAI,MAAM,CAAC,MAAM,CAAC,UAAU,CAAC,EAAE,CAAC;QACpD,qBAAM,CAAC,EAAE,CAAC,OAAO,WAAW,KAAK,QAAQ,IAAI,WAAW,KAAK,IAAI;YAC/D,WAAW,CAAC,QAAQ,IAAI,qBAAS,EACjC,qBAAqB,WAAW,CAAC,QAAQ,GAAG,CAAC,CAAA;QAE/C,qBAAM,CAAC,EAAE,CAAC,WAAW,CAAC,QAAQ,IAAI,OAAO,EACvC,2BAA2B,WAAW,CAAC,QAAQ,GAAG,CAAC,CAAA;QAErD,MAAM,MAAM,GAAwB,OAAO,CAAC,WAAW,CAAC,QAAkC,CAAC,CAAA;QAE3F,MAAM,CAAC,QAAQ,CAAC,WAAW,EAAE,YAAY,WAAW,CAAC,QAAQ,cAAc,CAAC,CAAA;IAC9E,CAAC;AACH,CAAC"}

package/transpiled/Aspect.d.ts

@@ -0,0 +1,8 @@
+import { Connector, type extensions } from '@toa.io/core';
+import { type Storage, type Storages } from './Storage';
+export declare class Aspect extends Connector implements extensions.Aspect {
+    readonly name = "storages";
+    private readonly storages;
+    constructor(storages: Storages);
+    invoke(name: string, method: keyof Storage, ...args: unknown[]): unknown;
+}

package/transpiled/Aspect.js

@@ -0,0 +1,25 @@
+"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 {
+    name = 'storages';
+    storages;
+    constructor(storages) {
+        super();
+        this.storages = storages;
+    }
+    invoke(name, method, ...args) {
+        const storage = this.storages[name];
+        node_assert_1.default.ok(storage !== undefined, `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

@@ -0,0 +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"}

package/transpiled/Entry.d.ts

@@ -0,0 +1,14 @@
+export interface Entry {
+    id: string;
+    size: number;
+    type: string;
+    created: number;
+    variants: Variant[];
+    meta: Record<string, unknown>;
+}
+interface Variant {
+    name: string;
+    size: number;
+    type: string;
+}
+export {};

package/transpiled/Entry.js

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

package/transpiled/Entry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Entry.js","sourceRoot":"","sources":["../source/Entry.ts"],"names":[],"mappings":""}

package/transpiled/Factory.d.ts

@@ -0,0 +1,9 @@
+import { Aspect } from './Aspect';
+export declare class Factory {
+    private readonly annotation;
+    constructor();
+    aspect(): Aspect;
+    private createStorages;
+    private createStorage;
+    private resolveSecrets;
+}

package/transpiled/Factory.js

@@ -0,0 +1,53 @@
+"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 {
+    annotation;
+    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);
+    }
+    aspect() {
+        const storages = this.createStorages();
+        return new Aspect_1.Aspect(storages);
+    }
+    createStorages() {
+        const storages = {};
+        for (const [name, declaration] of Object.entries(this.annotation))
+            storages[name] = this.createStorage(name, declaration);
+        return storages;
+    }
+    createStorage(name, declaration) {
+        const { provider: providerId, ...options } = declaration;
+        const Provider = providers_1.providers[providerId];
+        const secrets = this.resolveSecrets(name, Provider);
+        const provider = new Provider(options, secrets);
+        return new Storage_1.Storage(provider);
+    }
+    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`);
+            secrets[secret.name] = value;
+        }
+        return secrets;
+    }
+}
+exports.Factory = Factory;
+//# sourceMappingURL=Factory.js.map

package/transpiled/Factory.js.map

@@ -0,0 +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"}

package/transpiled/Provider.d.ts

@@ -0,0 +1,20 @@
+/// <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 put(path: string, filename: string, stream: Readable): Promise<void>;
+    abstract delete(path: string): Promise<void>;
+    abstract move(from: string, to: string): Promise<void>;
+}
+export interface ProviderConstructor {
+    readonly SECRETS: readonly ProviderSecret[];
+    prototype: Provider;
+    new (options: any, secrets?: ProviderSecrets): Provider;
+}

package/transpiled/Provider.js

@@ -0,0 +1,36 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || function (mod) {
+    if (mod && mod.__esModule) return mod;
+    var result = {};
+    if (mod != null) for (var k in mod) if (k !== "default" && Object.prototype.hasOwnProperty.call(mod, k)) __createBinding(result, mod, k);
+    __setModuleDefault(result, mod);
+    return result;
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Provider = void 0;
+const assert = __importStar(require("node:assert"));
+class Provider {
+    static SECRETS = [];
+    constructor(_, secrets) {
+        for (const { name, optional = false } of new.target.SECRETS)
+            assert.ok(optional || secrets?.[name] !== undefined, `Missing secret '${name}'`);
+    }
+}
+exports.Provider = Provider;
+//# sourceMappingURL=Provider.js.map

package/transpiled/Provider.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"Provider.js","sourceRoot":"","sources":["../source/Provider.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;AACA,oDAAqC;AASrC,MAAsB,QAAQ;IACrB,MAAM,CAAU,OAAO,GAA8B,EAAE,CAAA;IAE9D,YAAoB,CAAU,EAAE,OAAyB;QACvD,KAAK,MAAM,EAAE,IAAI,EAAE,QAAQ,GAAG,KAAK,EAAE,IAAI,GAAG,CAAC,MAAM,CAAC,OAAO;YACzD,MAAM,CAAC,EAAE,CAAC,QAAQ,IAAI,OAAO,EAAE,CAAC,IAAI,CAAC,KAAK,SAAS,EAAE,mBAAmB,IAAI,GAAG,CAAC,CAAA;IACpF,CAAC;;AANH,4BAeC"}

package/transpiled/Scanner.d.ts

@@ -0,0 +1,26 @@
+/// <reference types="node" />
+/// <reference types="node" />
+import { PassThrough, type TransformCallback } from 'node:stream';
+export declare class Scanner extends PassThrough {
+    size: number;
+    type: string;
+    error: Error | null;
+    private readonly hash;
+    private readonly claim?;
+    private readonly accept?;
+    private position;
+    private detected;
+    private readonly chunks;
+    constructor(control?: ScanOptions);
+    digest(): string;
+    _transform(buffer: Buffer, encoding: BufferEncoding, callback: TransformCallback): void;
+    private readonly process;
+    private complete;
+    private verify;
+    private match;
+    private interrupt;
+}
+export interface ScanOptions {
+    claim?: string;
+    accept?: string;
+}

package/transpiled/Scanner.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.Scanner = void 0;
+const node_stream_1 = require("node:stream");
+const node_crypto_1 = require("node:crypto");
+const agent_1 = require("@toa.io/agent");
+const error_value_1 = require("error-value");
+class Scanner extends node_stream_1.PassThrough {
+    size = 0;
+    type = 'application/octet-stream';
+    error = null;
+    hash = (0, node_crypto_1.createHash)('md5');
+    claim;
+    accept;
+    position = 0;
+    detected = false;
+    chunks = [];
+    constructor(control) {
+        super();
+        this.claim = control?.claim;
+        this.accept = control?.accept;
+    }
+    digest() {
+        return this.hash.digest('hex');
+    }
+    _transform(buffer, encoding, callback) {
+        super._transform(buffer, encoding, callback);
+        this.process(buffer);
+    }
+    process = (buffer) => {
+        this.size += buffer.length;
+        this.hash.update(buffer);
+        if (this.detected)
+            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();
+    };
+    complete() {
+        const header = Buffer.concat(this.chunks).toString('hex');
+        const signature = SIGNATURES
+            .find(({ hex, off }) => header.slice(off, off + hex.length) === hex);
+        const type = signature?.type ?? this.claim;
+        if (type !== undefined) {
+            this.match(type);
+            this.type = type;
+        }
+        this.verify(signature);
+        this.detected = true;
+    }
+    verify(signature) {
+        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);
+    }
+    match(type) {
+        if (this.accept === undefined)
+            return;
+        const unacceptable = (0, agent_1.negotiate)(this.accept, [type]) === null;
+        if (unacceptable)
+            this.interrupt(ERR_NOT_ACCEPTABLE);
+    }
+    interrupt(error) {
+        this.error = error;
+        this.end();
+    }
+}
+exports.Scanner = Scanner;
+// https://en.wikipedia.org/wiki/List_of_file_signatures
+const SIGNATURES = [
+    { hex: 'ffd8ffe0', off: 0, type: 'image/jpeg' },
+    { hex: 'ffd8ffe1', off: 0, type: 'image/jpeg' },
+    { hex: 'ffd8ffee', off: 0, type: 'image/jpeg' },
+    { hex: 'ffd8ffdb', off: 0, type: 'image/jpeg' },
+    { hex: '89504e47', off: 0, type: 'image/png' },
+    { hex: '47494638', off: 0, type: 'image/gif' },
+    { hex: '52494646', off: 0, type: 'image/webp' },
+    { hex: '4a584c200d0a870a', off: 8, type: 'image/jxl' },
+    { hex: '6674797068656963', off: 8, type: 'image/heic' },
+    { hex: '6674797061766966', off: 8, type: 'image/avif' }
+    /*
+    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`.
+     */
+];
+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 = (0, error_value_1.Err)('TYPE_MISMATCH');
+const ERR_NOT_ACCEPTABLE = (0, error_value_1.Err)('NOT_ACCEPTABLE');
+//# sourceMappingURL=Scanner.js.map

package/transpiled/Scanner.js.map

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

package/transpiled/Storage.d.ts

@@ -0,0 +1,32 @@
+/// <reference types="node" />
+import { Readable } from 'node:stream';
+import type { ScanOptions } from './Scanner';
+import type { Provider } from './Provider';
+import type { Entry } from './Entry';
+export declare class Storage {
+    private readonly provider;
+    constructor(provider: Provider);
+    put(path: string, stream: Readable, options?: Options): Maybe<Entry>;
+    get(path: string): Maybe<Entry>;
+    fetch(path: string): Maybe<Readable>;
+    delete(path: string): Maybe<void>;
+    list(path: string): Promise<string[]>;
+    permute(path: string, ids: string[]): Maybe<void>;
+    conceal(path: string): Maybe<void>;
+    reveal(path: string): Maybe<void>;
+    diversify(path: string, name: string, stream: Readable): Maybe<void>;
+    annotate(path: string, key: string, value?: unknown): Maybe<void>;
+    private transit;
+    private persist;
+    private create;
+    private save;
+    private enroll;
+    private parse;
+}
+type Maybe<T> = Promise<T | Error>;
+type Meta = Record<string, string>;
+interface Options extends ScanOptions {
+    meta?: Meta;
+}
+export type Storages = Record<string, Storage>;
+export {};