@ido_kawaz/storage-client 1.0.0

package/README.md

@@ -0,0 +1,95 @@
+# @kawaz/storage-client
+
+AWS S3 storage client library for Kawaz services with support for multipart uploads and bucket management.
+
+## Installation
+
+```bash
+npm install @kawaz/storage-client
+```
+
+## Usage
+
+### Initialize StorageClient
+
+```typescript
+import { StorageClient } from '@kawaz/storage-client';
+import { Readable } from 'stream';
+
+const client = new StorageClient({
+  region: 'us-east-1',
+  credentials: {
+    accessKeyId: 'YOUR_ACCESS_KEY',
+    secretAccessKey: 'YOUR_SECRET_KEY'
+  },
+  partSize: 5 * 1024 * 1024,      // 5MB (optional, default varies)
+  maxConcurrency: 4                // Maximum concurrent parts (optional)
+});
+```
+
+### Ensure Bucket Exists
+
+Checks if a bucket exists, creates it if not.
+
+```typescript
+await client.ensureBucket('my-bucket');
+```
+
+### Upload Objects
+
+Upload files or streams to S3 with optional automatic bucket creation:
+
+```typescript
+const fileStream = fs.createReadStream('path/to/file');
+
+await client.uploadObject('my-bucket', 'path/to/object', fileStream, {
+  ensureBucket: true  // Automatically create bucket if it doesn't exist
+});
+```
+
+The upload progress is logged to console as it progresses.
+
+### Delete Bucket
+
+Remove an empty bucket:
+
+```typescript
+await client.deleteBucket('my-bucket');
+```
+
+## Configuration
+
+`StorageClientConfig` extends AWS S3ClientConfig with additional options:
+
+- `region` (required): AWS region (e.g., 'us-east-1')
+- `credentials` (optional): AWS credentials object with `accessKeyId` and `secretAccessKey`
+- `endpoint` (optional): Custom S3-compatible endpoint (e.g., MinIO, LocalStack)
+- `partSize` (optional): Size of each part in multipart uploads (bytes)
+- `maxConcurrency` (optional): Maximum concurrent parts during upload
+
+## Error Handling
+
+The library throws `StorageError` exceptions with operation details:
+
+```typescript
+import { StorageError } from '@kawaz/storage-client';
+
+try {
+  await client.uploadObject('bucket', 'key', stream);
+} catch (error) {
+  if (error instanceof StorageError) {
+    console.error('Storage operation failed:', error.message);
+  }
+}
+```
+
+## Exports
+
+- `StorageClient`: Main client class
+- `StorageClientConfig`: Configuration interface
+- `StorageError`: Error class
+- `UploadObjectOptions`: Upload options interface
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,8 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageError = exports.StorageClient = void 0;
+var storageClient_1 = require("./storageClient");
+Object.defineProperty(exports, "StorageClient", { enumerable: true, get: function () { return storageClient_1.StorageClient; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "StorageError", { enumerable: true, get: function () { return types_1.StorageError; } });
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;AAAA,iDAAgD;AAAvC,8GAAA,aAAa,OAAA;AACtB,iCAAiF;AAAnD,qGAAA,YAAY,OAAA"}

package/dist/storageClient.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageClient = void 0;
+const client_s3_1 = require("@aws-sdk/client-s3");
+const lib_storage_1 = require("@aws-sdk/lib-storage");
+const types_1 = require("./types");
+class StorageClient {
+    constructor(config) {
+        this.config = config;
+        this.ensureBucket = async (bucketName) => {
+            await this.client.send(new client_s3_1.HeadBucketCommand({ Bucket: bucketName })).catch(async (error) => {
+                if (error.name === 'NotFound') {
+                    await this.client.send(new client_s3_1.CreateBucketCommand({ Bucket: bucketName }));
+                }
+                else {
+                    throw new types_1.StorageError("ensureBucket", error, { bucketName });
+                }
+            });
+        };
+        this.deleteBucket = async (bucketName) => {
+            await this.client.send(new client_s3_1.DeleteBucketCommand({ Bucket: bucketName })).catch((error) => {
+                if (error.name !== 'NoSuchBucket') {
+                    throw new types_1.StorageError("deleteBucket", error, { bucketName });
+                }
+            });
+        };
+        this.uploadObject = async (bucketName, objectKey, objectData, options) => {
+            if (options?.ensureBucket) {
+                await this.ensureBucket(bucketName);
+            }
+            try {
+                const upload = new lib_storage_1.Upload({
+                    client: this.client,
+                    params: { Bucket: bucketName, Key: objectKey, Body: objectData },
+                    queueSize: this.config.maxConcurrency,
+                    partSize: this.config.partSize
+                });
+                upload.on("httpUploadProgress", (progress) => {
+                    console.log(`Upload progress for ${objectKey}: ${progress.loaded / progress.total * 100}%`);
+                });
+                await upload.done();
+            }
+            catch (error) {
+                if (error instanceof client_s3_1.S3ServiceException) {
+                    throw new types_1.StorageError("uploadObject", error, { bucketName, objectKey });
+                }
+                throw error;
+            }
+        };
+        this.client = new client_s3_1.S3Client(config);
+    }
+}
+exports.StorageClient = StorageClient;
+//# sourceMappingURL=storageClient.js.map

package/dist/storageClient.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"storageClient.js","sourceRoot":"","sources":["../src/storageClient.ts"],"names":[],"mappings":";;;AAAA,kDAA+H;AAC/H,sDAA8C;AAE9C,mCAAiF;AAEjF,MAAa,aAAa;IAEtB,YAA6B,MAA2B;QAA3B,WAAM,GAAN,MAAM,CAAqB;QAGxD,iBAAY,GAAG,KAAK,EAAE,UAAkB,EAAE,EAAE;YACxC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,6BAAiB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,KAAK,EAAE,KAAyB,EAAE,EAAE;gBAC5G,IAAI,KAAK,CAAC,IAAI,KAAK,UAAU,EAAE,CAAC;oBAC5B,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,+BAAmB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC;gBAC5E,CAAC;qBAAM,CAAC;oBACJ,MAAM,IAAI,oBAAY,CAAC,cAAc,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;gBAClE,CAAC;YACL,CAAC,CAAC,CAAC;QACP,CAAC,CAAC;QACF,iBAAY,GAAG,KAAK,EAAE,UAAkB,EAAE,EAAE;YACxC,MAAM,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,+BAAmB,CAAC,EAAE,MAAM,EAAE,UAAU,EAAE,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,KAAyB,EAAE,EAAE;gBACxG,IAAI,KAAK,CAAC,IAAI,KAAK,cAAc,EAAE,CAAC;oBAChC,MAAM,IAAI,oBAAY,CAAC,cAAc,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,CAAC,CAAC;gBAClE,CAAC;YACL,CAAC,CAAC,CAAC;QACP,CAAC,CAAC;QAEF,iBAAY,GAAG,KAAK,EAAE,UAAkB,EAAE,SAAiB,EAAE,UAAoB,EAAE,OAA6B,EAAE,EAAE;YAChH,IAAI,OAAO,EAAE,YAAY,EAAE,CAAC;gBACxB,MAAM,IAAI,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;YACxC,CAAC;YACD,IAAI,CAAC;gBACD,MAAM,MAAM,GAAG,IAAI,oBAAM,CAAC;oBACtB,MAAM,EAAE,IAAI,CAAC,MAAM;oBACnB,MAAM,EAAE,EAAE,MAAM,EAAE,UAAU,EAAE,GAAG,EAAE,SAAS,EAAE,IAAI,EAAE,UAAU,EAAE;oBAChE,SAAS,EAAE,IAAI,CAAC,MAAM,CAAC,cAAc;oBACrC,QAAQ,EAAE,IAAI,CAAC,MAAM,CAAC,QAAQ;iBACjC,CAAC,CAAA;gBACF,MAAM,CAAC,EAAE,CAAC,oBAAoB,EAAE,CAAC,QAAQ,EAAE,EAAE;oBACzC,OAAO,CAAC,GAAG,CAAC,uBAAuB,SAAS,KAAK,QAAQ,CAAC,MAAO,GAAG,QAAQ,CAAC,KAAM,GAAG,GAAG,GAAG,CAAC,CAAC;gBAClG,CAAC,CAAC,CAAC;gBACH,MAAM,MAAM,CAAC,IAAI,EAAE,CAAC;YACxB,CAAC;YAAC,OAAO,KAAK,EAAE,CAAC;gBACb,IAAI,KAAK,YAAY,8BAAkB,EAAE,CAAC;oBACtC,MAAM,IAAI,oBAAY,CAAC,cAAc,EAAE,KAAK,EAAE,EAAE,UAAU,EAAE,SAAS,EAAE,CAAC,CAAC;gBAC7E,CAAC;gBACD,MAAM,KAAK,CAAC;YAChB,CAAC;QACL,CAAC,CAAA;QAxCG,IAAI,CAAC,MAAM,GAAG,IAAI,oBAAQ,CAAC,MAAM,CAAC,CAAC;IACvC,CAAC;CAwCJ;AA5CD,sCA4CC"}

package/dist/types.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageError = void 0;
+class StorageError extends Error {
+    constructor(operation, error, details) {
+        const message = `Storage error: ${JSON.stringify({ operation, error: error.name, ...details })}`;
+        super(message);
+    }
+}
+exports.StorageError = StorageError;
+//# sourceMappingURL=types.js.map

package/dist/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":";;;AAOA,MAAa,YAAa,SAAQ,KAAK;IACnC,YAAY,SAAiB,EAAE,KAAyB,EAAE,OAAW;QACjE,MAAM,OAAO,GAAG,kBAAkB,IAAI,CAAC,SAAS,CAAC,EAAE,SAAS,EAAE,KAAK,EAAE,KAAK,CAAC,IAAI,EAAE,GAAG,OAAO,EAAE,CAAC,EAAE,CAAC;QACjG,KAAK,CAAC,OAAO,CAAC,CAAC;IACnB,CAAC;CACJ;AALD,oCAKC"}

package/package.json

@@ -0,0 +1,34 @@
+{
+  "name": "@ido_kawaz/storage-client",
+  "version": "1.0.0",
+  "description": "Storage client library for Kawaz Plus services",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "npm run clean && tsc",
+    "build:watch": "tsc --watch",
+    "build:advanced": "npm run clean:advanced && npm i && tsc",
+    "clean": "rimraf dist",
+    "clean:advanced": "rimraf dist node_modules package-lock.json",
+    "package": "npm run build:advanced && npm publish --access public"
+  },
+  "keywords": [
+    "storage",
+    "s3",
+    "aws"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.985.0",
+    "@aws-sdk/lib-storage": "^3.985.0"
+  },
+  "devDependencies": {
+    "@types/node": "^25.2.3",
+    "rimraf": "^6.0.0",
+    "typescript": "^5.9.3"
+  }
+}