@storecraft/storage-s3-compatible 1.0.10 → 1.0.12

package/README.md

@@ -28,10 +28,10 @@ npm i @storecraft/storage-s3-compatible
 import { R2, S3, DigitalOceanSpaces, S3CompatibleStorage } from '@storecraft/storage-s3-compatible'
 
 const storage = new R2({
-  accessKeyId: process.env.R2_ACCESS_KEY_ID,
-  account_id: process.env.R2_ACCOUNT_ID,
-  bucket: process.env.R2_BUCKET,
-  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY
+  accessKeyId: process.env.S3_ACCESS_KEY_ID,
+  account_id: process.env.CF_ACCOUNT_ID,
+  bucket: process.env.S3_BUCKET,
+  secretAccessKey: process.env.S3_SECRET_ACCESS_KEY
 });
 
 // write
@@ -69,12 +69,7 @@ const app = new App(
 .withPlatform(new NodePlatform())
 .withDatabase(new MongoDB())
 .withStorage(
-  new R2(
-    process.env.R2_BUCKET, 
-    process.env.R2_ACCOUNT_ID, 
-    process.env.R2_ACCESS_KEY_ID, 
-    process.env.R2_SECRET_ACCESS_KEY
-  )
+  new R2() // config will be inferred by env variables
 );
 
 await app.init();

package/adapter.js

@@ -1,3 +1,8 @@
+/**
+ * @import { AwsS3Config, Config, R2Config } from './types.public.js'
+ * @import { ENV } from '@storecraft/core';
+ * @import { storage_driver, StorageFeatures } from '@storecraft/core/storage'
+ */
 import { App } from '@storecraft/core'
 import { AwsClient } from './aws4fetch.js';
 
@@ -23,38 +28,23 @@ const infer_content_type = (name) => {
   return type ?? 'application/octet-stream';
 }
 
-
-/**
- * @typedef {import('./types.public.d.ts').Config} Config
- */
-
 /**
  * @description The base S3 compatible class
  * 
- * @typedef {import('@storecraft/core/storage').storage_driver} storage
- * 
- * @implements {storage}
+ * @implements {storage_driver}
  */
 export class S3CompatibleStorage {
   
+  /** @satisfies {ENV<Config>} */
+  static EnvConfig = /** @type{const} */ ({
+    accessKeyId: 'S3_ACCESS_KEY_ID',
+    secretAccessKey: 'S3_SECRET_ACCESS_KEY',
+    bucket: 'S3_BUCKET',
+    region: 'S3_REGION',
+  });
+
   /** @type {AwsClient} */ #_client;
   /** @type {Config} */ #_config;
-  /** @type {string} */ #_url;
-
-  /**
-   * 
-   * @param {Config} options 
-   */
-  #compute_url(options) {
-    const url = new URL(options.endpoint);
-    if(options.forcePathStyle) {
-      url.pathname = options.bucket;
-    } else {
-      url.host = `${options.bucket}.${url.host}`;
-    }
-    return url.toString();
-  }
-
 
   /**
    * 
@@ -62,20 +52,23 @@ export class S3CompatibleStorage {
    */
   constructor(config) {
     this.#_config = config;
-    this.#_client = new AwsClient({
-      accessKeyId: config.accessKeyId, secretAccessKey: config.secretAccessKey, 
-      region: config.region ?? 'auto', service: 's3'
-    });
-
-    this.#_url = this.#compute_url(config);
   }
 
-  get url() { return this.#_url; }
-  get client() { return this.#_client; }
   get config() { return this.#_config; }
+  get client() { 
+    this.#_client = this.#_client ?? new AwsClient(
+      {
+        accessKeyId: this.config.accessKeyId, 
+        secretAccessKey: this.config.secretAccessKey, 
+        region: this.config.region ?? 'auto', 
+        service: 's3'
+      }
+    );
+    return this.#_client; 
+  }
 
   features() {
-    /** @type {import('@storecraft/core/storage').StorageFeatures} */
+    /** @type {StorageFeatures} */
     const f = {
       supports_signed_urls: true
     }
@@ -85,9 +78,16 @@ export class S3CompatibleStorage {
 
   /**
    * 
-   * @type {storage["init"]}
+   * @type {storage_driver["init"]}
    */
-  async init(app) { return this; }
+  async init(app) { 
+    this.config.accessKeyId ??= app.platform.env[S3CompatibleStorage.EnvConfig.accessKeyId];
+    this.config.secretAccessKey ??= app.platform.env[S3CompatibleStorage.EnvConfig.secretAccessKey];
+    this.config.bucket ??= app.platform.env[S3CompatibleStorage.EnvConfig.bucket];
+    // @ts-ignore
+    this.config.region ??= app.platform.env[S3CompatibleStorage.EnvConfig.region];
+    return this; 
+  }
 
   // puts
 
@@ -118,7 +118,7 @@ export class S3CompatibleStorage {
 
   /**
    * 
-   * @type {storage["putBlob"]}
+   * @type {storage_driver["putBlob"]}
    */
   async putBlob(key, blob) {
     return this.#put_internal(key, blob);
@@ -126,7 +126,7 @@ export class S3CompatibleStorage {
 
   /**
    * 
-   * @type {storage["putArraybuffer"]}
+   * @type {storage_driver["putArraybuffer"]}
    */
   async putArraybuffer(key, buffer) {
     return this.#put_internal(key, buffer);
@@ -134,7 +134,7 @@ export class S3CompatibleStorage {
 
   /**
    * 
-   * @type {storage["putStream"]}
+   * @type {storage_driver["putStream"]}
    */
   async putStream(key, stream, meta={}, bytesLength=0) {
     const extra_headers = {};
@@ -150,7 +150,7 @@ export class S3CompatibleStorage {
 
   /**
    * 
-   * @type {storage["putSigned"]}
+   * @type {storage_driver["putSigned"]}
    */
   async putSigned(key) {
     const url = new URL(this.get_file_url(key));
@@ -172,9 +172,19 @@ export class S3CompatibleStorage {
 
   // gets
 
+  get url() {
+    const url = new URL(this.config.endpoint);
+    if(this.config.forcePathStyle) {
+      url.pathname = this.config.bucket;
+    } else {
+      url.host = `${this.config.bucket}.${url.host}`;
+    }
+    return url.toString();
+  }
+
   /** @param {string} key  */
   get_file_url(key) {
-    return `${this.#_url}/${key}`;
+    return `${this.url}/${key}`;
   }
 
   /** @param {string} key  */
@@ -183,7 +193,7 @@ export class S3CompatibleStorage {
   }
 
   /**
-   * @type {storage["getArraybuffer"]}
+   * @type {storage_driver["getArraybuffer"]}
    */
   async getArraybuffer(key) {
     const r = await this.#get_request(key);
@@ -199,7 +209,7 @@ export class S3CompatibleStorage {
 
   /**
    * 
-   * @type {storage["getBlob"]}
+   * @type {storage_driver["getBlob"]}
    */
   async getBlob(key) {
     const r = await this.#get_request(key);
@@ -214,7 +224,7 @@ export class S3CompatibleStorage {
   }
 
   /**
-   * @type {storage["getStream"]}
+   * @type {storage_driver["getStream"]}
    */
   async getStream(key) {
     const r = await this.#get_request(key);
@@ -231,7 +241,7 @@ export class S3CompatibleStorage {
 
   /**
    * 
-   * @type {storage["getSigned"]}
+   * @type {storage_driver["getSigned"]}
    */
   async getSigned(key) {
     const url = new URL(this.get_file_url(key));
@@ -256,7 +266,7 @@ export class S3CompatibleStorage {
 
   /**
    * 
-   * @type {storage["remove"]}
+   * @type {storage_driver["remove"]}
    */
   async remove(key) {
     const r = await this.client.fetch(
@@ -271,58 +281,117 @@ export class S3CompatibleStorage {
  */
 export class R2 extends S3CompatibleStorage {
 
+  /** @satisfies {ENV<R2Config>} */
+  static R2EnvConfig = /** @type{const} */ ({
+    accessKeyId: 'S3_ACCESS_KEY_ID',
+    secretAccessKey: 'S3_SECRET_ACCESS_KEY',
+    bucket: 'S3_BUCKET',
+    account_id: 'CF_ACCOUNT_ID',
+  });
+
   /**
-   * @param {import('./types.public.d.ts').R2Config} config
+   * @param {R2Config} config
    */
-  constructor({bucket, account_id, accessKeyId, secretAccessKey}) {
+  constructor(config={}) {
     super(
       {
-        endpoint: `https://${account_id}.r2.cloudflarestorage.com`,
-        accessKeyId, secretAccessKey, bucket, 
-        forcePathStyle: true, region: 'auto'
+        endpoint: config.account_id ? 
+          `https://${config.account_id}.r2.cloudflarestorage.com` : 
+          undefined,
+        accessKeyId: config.accessKeyId, 
+        secretAccessKey:config.secretAccessKey, 
+        bucket: config.bucket, 
+        forcePathStyle: true, 
+        region: 'auto'
       }
-    )
+    );
+    this.r2_config = config;
   }
 
+  /** @type {S3CompatibleStorage["init"]} */
+  init = async (app) => {
+    await super.init(app);
+    this.r2_config.account_id ??= app.platform.env[R2.R2EnvConfig.account_id];
+    this.config.endpoint ??= `https://${this.r2_config.account_id}.r2.cloudflarestorage.com`;
+    return this;
+  }
+  
 }
 
+
 /**
  * Amazon S3
  */
 export class S3 extends S3CompatibleStorage {
 
+  /** @satisfies {ENV<AwsS3Config>} */
+  static AWSS3EnvConfig = /** @type{const} */ ({
+    ...S3CompatibleStorage.EnvConfig
+  });
+
   /**
-   * @param {import('./types.public.d.ts').AwsS3Config} config
+   * @param {Partial<AwsS3Config>} config
    */
-  constructor({bucket, region, accessKeyId, secretAccessKey, forcePathStyle=false}) {
+  constructor(config = {}) {
     super(
       {
-        endpoint: `https://s3${region ? ('.'+region) : ''}.amazonaws.com`,
-        accessKeyId, secretAccessKey, 
-        bucket, forcePathStyle, region
+        endpoint: config.region ? `https://s3.${config.region}.amazonaws.com` : undefined,
+        accessKeyId: config.accessKeyId,
+        secretAccessKey: config.secretAccessKey, 
+        bucket: config.bucket, 
+        forcePathStyle: config.forcePathStyle ?? false, 
+        region: config.region
       }
     )
   }
 
+  /** @type {S3CompatibleStorage["init"]} */
+  init = async (app) => {
+    await super.init(app);
+    this.config.endpoint = `https://s3${this.config.region ? 
+      ('.'+this.config.region) : ''}.amazonaws.com`;
+    return this;
+  }
+
 }
 
+
 /**
  * Digital Ocean spaces
  */
 export class DigitalOceanSpaces extends S3CompatibleStorage {
 
+  /** @satisfies {ENV<AwsS3Config>} */
+  static DOEnvConfig = /** @type{const} */ ({
+    ...S3CompatibleStorage.EnvConfig
+  });
+
   /**
-   * @param {Omit<import('./types.public.d.ts').Config, 'endpoint' | 'forcePathStyle'>} config
+   * @param {Partial<Omit<Config, 'endpoint' | 'forcePathStyle'>>} config
    */
-  constructor({bucket, region, accessKeyId, secretAccessKey}) {
+  constructor(config = {}) {
     super(
       {
-        endpoint: `https://${region}.digitaloceanspaces.com`,
-        accessKeyId, secretAccessKey, 
-        bucket, forcePathStyle: false, region: 'auto'
+        endpoint: config.region ? 
+          `https://${config.region}.digitaloceanspaces.com` : undefined,
+        accessKeyId: config.accessKeyId, 
+        secretAccessKey: config.secretAccessKey, 
+        bucket: config.bucket, 
+        forcePathStyle: false, region: 'auto'
       }
     )
   }
 
+  /** @type {S3CompatibleStorage["init"]} */
+  init = async (app) => {
+    await super.init(app);
+    this.config.endpoint = this.config.region ? 
+      `https://${this.config.region}.digitaloceanspaces.com` : 
+      undefined;
+
+    return this;
+  }
+
+
 }
 

package/aws4fetch.js

@@ -1,4 +1,4 @@
-// @ts-check
+// @ts-nocheck
 
 /**
  * @license MIT <https://opensource.org/licenses/MIT>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@storecraft/storage-s3-compatible",
-  "version": "1.0.10",
+  "version": "1.0.12",
   "description": "Official S3-Compatible Storage adapter for storecraft",
   "license": "MIT",
   "author": "Tomer Shalev (https://github.com/store-craft)",

package/tests/storage.aws-s3.test.js

@@ -16,6 +16,7 @@ const storage = new S3({
   accessKeyId: process.env.S3_ACCESS_KEY_ID,
   bucket: process.env.S3_BUCKET,
   forcePathStyle: FORCE_PATH_STYLE,
+  // @ts-ignore
   region: process.env.S3_REGION,
   secretAccessKey: process.env.S3_SECRET_KEY
 });

package/tests/storage.r2.test.js

@@ -12,10 +12,10 @@ const areBlobsEqual = async (blob1, blob2) => {
 };
 
 const storage = new R2({
-  accessKeyId: process.env.R2_ACCESS_KEY_ID,
-  account_id: process.env.R2_ACCOUNT_ID,
-  bucket: process.env.R2_BUCKET,
-  secretAccessKey: process.env.R2_SECRET_ACCESS_KEY
+  accessKeyId: process.env.S3_ACCESS_KEY_ID,
+  account_id: process.env.CF_ACCOUNT_ID,
+  bucket: process.env.S3_BUCKET,
+  secretAccessKey: process.env.S3_SECRET_ACCESS_KEY
 });
 
 const suite = storage_test_runner.create(storage);

package/tests/storage.s3-compatible.test.js

@@ -6,12 +6,13 @@ const FORCE_PATH_STYLE = true;
 
 const storage = new S3CompatibleStorage(
   {
-    accessKeyId: process.env.ACCESS_KEY_ID,
-    secretAccessKey: process.env.SECRET_ACCESS_KEY,
-    bucket: process.env.BUCKET,
+    accessKeyId: process.env.S3_ACCESS_KEY_ID,
+    secretAccessKey: process.env.S3_SECRET_ACCESS_KEY,
+    bucket: process.env.S3_BUCKET,
     endpoint: process.env.ENDPOINT,
     forcePathStyle: FORCE_PATH_STYLE,
-    region: process.env.REGION
+    // @ts-ignore
+    region: process.env.S3_REGION
   }
 );
 

package/types.public.d.ts

@@ -1,21 +1,58 @@
 export { DigitalOceanSpaces, R2, S3, S3CompatibleStorage } from './adapter.js';
 
 export type Config = {
-  endpoint: string;
-  bucket: string;
-  accessKeyId: string;
-  secretAccessKey: string;
-  region: string;
-  forcePathStyle: boolean;
+  /** Optional, complete endpoint if you know it in advance */
+  endpoint?: string;
+  /** If missing, will be inferred by env variable `S3_BUCKET` */
+  bucket?: string;
+  /** If missing, will be inferred by env variable `S3_ACCESS_KEY_ID` */
+  accessKeyId?: string;
+  /** If missing, will be inferred by env variable `S3_SECRET_ACCESS_KEY` */
+  secretAccessKey?: string;
+  /** If missing, will be inferred by env variable `S3_REGION` */
+  region?: 'auto' | AWSRegion;
+  forcePathStyle?: boolean;
 }
 
 export type R2Config = Omit<Config, 'region' | 'forcePathStyle' | 'endpoint'> & {
   /**
-   * @description cloudflare account id
+   * @description cloudflare account id. If missing will be inferred by env variable `CF_ACCOUNT_ID`
    */
-  account_id: string;
+  account_id?: string;
 };
 
 
 export type AwsS3Config = Omit<Config, 'endpoint'>;
 
+type AWSRegion = 
+  | "us-east-1"
+  | "us-east-2"
+  | "us-west-1"
+  | "us-west-2"
+  | "af-south-1"
+  | "ap-east-1"
+  | "ap-south-1"
+  | "ap-south-2"
+  | "ap-southeast-1"
+  | "ap-southeast-2"
+  | "ap-southeast-3"
+  | "ap-northeast-1"
+  | "ap-northeast-2"
+  | "ap-northeast-3"
+  | "ca-central-1"
+  | "ca-west-1"
+  | "eu-central-1"
+  | "eu-central-2"
+  | "eu-west-1"
+  | "eu-west-2"
+  | "eu-west-3"
+  | "eu-north-1"
+  | "eu-south-1"
+  | "eu-south-2"
+  | "me-central-1"
+  | "me-south-1"
+  | "sa-east-1"
+  | "us-gov-east-1"
+  | "us-gov-west-1"
+  | "cn-north-1"
+  | "cn-northwest-1";