@alepha/bucket-azure 0.7.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Feunard
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,21 @@
+# alepha/bucket/azure
+
+```ts
+import { $bucket } from "alepha/bucket";
+import { AzureBucketModule } from "alepha/bucket/azure";
+import { Alepha, run } from "alepha";
+
+class App {
+	images = $bucket()
+}
+
+const alepha = Alepha.create( {
+	env: {
+		AZ_STORAGE_CONNECTION_STRING: "",
+	},
+})
+	.with(AzureBucketModule)
+	.with(App);
+
+run(alepha);
+```

package/dist/index.cjs

@@ -0,0 +1,143 @@
+'use strict';
+
+var bucket = require('@alepha/bucket');
+var core = require('@alepha/core');
+var node_crypto = require('node:crypto');
+var datetime = require('@alepha/datetime');
+var file = require('@alepha/file');
+var storageBlob = require('@azure/storage-blob');
+
+const envSchema = core.t.object({
+  AZ_STORAGE_CONNECTION_STRING: core.t.string({
+    size: "long",
+    default: "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;"
+  })
+});
+class AzureFileStorageProvider {
+  log = core.$logger();
+  env = core.$env(envSchema);
+  bucketProvider = core.$inject(bucket.BucketDescriptorProvider);
+  dateTimeProvider = core.$inject(datetime.DateTimeProvider);
+  containers = {};
+  blobServiceClient;
+  options = {};
+  constructor() {
+    this.blobServiceClient = storageBlob.BlobServiceClient.fromConnectionString(
+      this.env.AZ_STORAGE_CONNECTION_STRING,
+      this.storagePipelineOptions()
+    );
+  }
+  storagePipelineOptions() {
+    return {};
+  }
+  async createContainer(containerName) {
+    if (this.containers[containerName]) {
+      return this.containers[containerName];
+    }
+    const container = await this.createContainerClient(containerName);
+    this.containers[containerName] = container;
+    return container;
+  }
+  async upload(bucketName, file2, fileId) {
+    fileId ??= this.createId();
+    const block = this.getBlock(bucketName, fileId);
+    const metadata = {
+      name: file2.name,
+      type: file2.type
+    };
+    if (file2.filepath) {
+      await block.uploadFile(file2.filepath, {
+        metadata,
+        blobHTTPHeaders: {
+          blobContentType: file2.type
+        }
+      });
+    } else if (file2.size > 0) {
+      await block.uploadData(await file2.arrayBuffer(), {
+        metadata,
+        blobHTTPHeaders: {
+          blobContentType: file2.type
+        }
+      });
+    } else {
+      throw new Error("Raw stream upload is not supported yet");
+    }
+    return fileId;
+  }
+  async download(bucketName, fileId) {
+    const block = this.getBlock(bucketName, fileId);
+    const blob = await block.download().catch((error) => {
+      if (error instanceof Error) {
+        throw new bucket.FileNotFoundError("Error downloading file", { cause: error });
+      }
+      throw error;
+    });
+    if (!blob.readableStreamBody) {
+      throw new bucket.FileNotFoundError("File not found - empty stream body");
+    }
+    return file.file(blob.readableStreamBody, blob.metadata);
+  }
+  async exists(bucketName, fileId) {
+    return await this.getBlock(bucketName, fileId).exists();
+  }
+  async delete(bucketName, fileId) {
+    try {
+      await this.getBlock(bucketName, fileId).delete();
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new bucket.FileNotFoundError("Error deleting file", { cause: error });
+      }
+      throw error;
+    }
+  }
+  getBlock(container, fileId) {
+    if (!this.containers[container]) {
+      throw new bucket.FileNotFoundError(
+        `File '${fileId}' not found - container '${container}' does not exists`
+      );
+    }
+    return this.containers[container].getBlockBlobClient(fileId);
+  }
+  onStart = core.$hook({
+    name: "start",
+    handler: async () => {
+      for (const bucket of this.bucketProvider.getBuckets()) {
+        const containerName = bucket.name.replaceAll("/", "-").toLowerCase();
+        this.log.debug(`Prepare container ${containerName}...`);
+        if (!this.containers[containerName]) {
+          this.containers[containerName] = await this.createContainerClient(containerName);
+        }
+        this.log.info(`Container ${bucket} OK`);
+      }
+    }
+  });
+  async createContainerClient(name) {
+    const container = this.blobServiceClient.getContainerClient(name);
+    await this.dateTimeProvider.deadline(
+      (abortSignal) => container.createIfNotExists({ abortSignal }),
+      { seconds: 5 }
+    );
+    return container;
+  }
+  createId() {
+    return node_crypto.randomUUID();
+  }
+}
+
+class AzureBucketModule {
+  name = "alepha/bucket/azure";
+  alepha = core.$inject(core.Alepha);
+  constructor() {
+    this.alepha.with(
+      {
+        default: true,
+        provide: bucket.FileStorageProvider,
+        use: AzureFileStorageProvider
+      },
+      bucket.BucketModule
+    );
+  }
+}
+
+exports.AzureBucketModule = AzureBucketModule;
+exports.AzureFileStorageProvider = AzureFileStorageProvider;

package/dist/index.d.ts

@@ -0,0 +1,103 @@
+import * as _alepha_core from '@alepha/core';
+import { Static, FileLike, Module, Alepha } from '@alepha/core';
+import { FileStorageProvider, BucketDescriptorProvider } from '@alepha/bucket';
+import { DateTimeProvider } from '@alepha/datetime';
+import { ContainerClient, BlobServiceClient, StoragePipelineOptions, BlockBlobClient } from '@azure/storage-blob';
+
+/** Symbol key applied to readonly types */
+declare const ReadonlyKind: unique symbol;
+/** Symbol key applied to optional types */
+declare const OptionalKind: unique symbol;
+/** Symbol key applied to types */
+declare const Hint: unique symbol;
+/** Symbol key applied to types */
+declare const Kind: unique symbol;
+
+type StringFormatOption = 'date-time' | 'time' | 'date' | 'email' | 'idn-email' | 'hostname' | 'idn-hostname' | 'ipv4' | 'ipv6' | 'uri' | 'uri-reference' | 'iri' | 'uuid' | 'iri-reference' | 'uri-template' | 'json-pointer' | 'relative-json-pointer' | 'regex' | ({} & string);
+type StringContentEncodingOption = '7bit' | '8bit' | 'binary' | 'quoted-printable' | 'base64' | ({} & string);
+interface StringOptions extends SchemaOptions {
+    /** The maximum string length */
+    maxLength?: number;
+    /** The minimum string length */
+    minLength?: number;
+    /** A regular expression pattern this string should match */
+    pattern?: string;
+    /** A format this string should match */
+    format?: StringFormatOption;
+    /** The content encoding for this string */
+    contentEncoding?: StringContentEncodingOption;
+    /** The content media type for this string */
+    contentMediaType?: string;
+}
+interface TString extends TSchema, StringOptions {
+    [Kind]: 'String';
+    static: string;
+    type: 'string';
+}
+
+interface SchemaOptions {
+    $schema?: string;
+    /** Id for this schema */
+    $id?: string;
+    /** Title of this schema */
+    title?: string;
+    /** Description of this schema */
+    description?: string;
+    /** Default value for this schema */
+    default?: any;
+    /** Example values matching this schema */
+    examples?: any;
+    /** Optional annotation for readOnly */
+    readOnly?: boolean;
+    /** Optional annotation for writeOnly */
+    writeOnly?: boolean;
+    [prop: string]: any;
+}
+interface TKind {
+    [Kind]: string;
+}
+interface TSchema extends TKind, SchemaOptions {
+    [ReadonlyKind]?: string;
+    [OptionalKind]?: string;
+    [Hint]?: string;
+    params: unknown[];
+    static: unknown;
+}
+
+declare const envSchema: _alepha_core.TObject<{
+    AZ_STORAGE_CONNECTION_STRING: TString;
+}>;
+declare module "@alepha/core" {
+    interface Env extends Partial<Static<typeof envSchema>> {
+    }
+}
+declare class AzureFileStorageProvider implements FileStorageProvider {
+    protected readonly log: _alepha_core.Logger;
+    protected readonly env: {
+        AZ_STORAGE_CONNECTION_STRING: string;
+    };
+    protected readonly bucketProvider: BucketDescriptorProvider;
+    protected readonly dateTimeProvider: DateTimeProvider;
+    protected readonly containers: Record<string, ContainerClient>;
+    protected readonly blobServiceClient: BlobServiceClient;
+    protected readonly options: StoragePipelineOptions;
+    constructor();
+    storagePipelineOptions(): StoragePipelineOptions;
+    createContainer(containerName: string): Promise<ContainerClient>;
+    upload(bucketName: string, file: FileLike, fileId?: string): Promise<string>;
+    download(bucketName: string, fileId: string): Promise<FileLike>;
+    exists(bucketName: string, fileId: string): Promise<boolean>;
+    delete(bucketName: string, fileId: string): Promise<void>;
+    getBlock(container: string, fileId: string): BlockBlobClient;
+    readonly onStart: _alepha_core.HookDescriptor<"start">;
+    protected createContainerClient(name: string): Promise<ContainerClient>;
+    protected createId(): string;
+}
+
+declare class AzureBucketModule implements Module {
+    readonly name = "alepha/bucket/azure";
+    protected readonly alepha: Alepha;
+    constructor();
+}
+
+export { AzureBucketModule, AzureFileStorageProvider };

package/dist/index.js

@@ -0,0 +1,140 @@
+import { BucketDescriptorProvider, FileNotFoundError, FileStorageProvider, BucketModule } from '@alepha/bucket';
+import { t, $logger, $env, $inject, $hook, Alepha } from '@alepha/core';
+import { randomUUID } from 'node:crypto';
+import { DateTimeProvider } from '@alepha/datetime';
+import { file } from '@alepha/file';
+import { BlobServiceClient } from '@azure/storage-blob';
+
+const envSchema = t.object({
+  AZ_STORAGE_CONNECTION_STRING: t.string({
+    size: "long",
+    default: "DefaultEndpointsProtocol=http;AccountName=devstoreaccount1;AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;"
+  })
+});
+class AzureFileStorageProvider {
+  log = $logger();
+  env = $env(envSchema);
+  bucketProvider = $inject(BucketDescriptorProvider);
+  dateTimeProvider = $inject(DateTimeProvider);
+  containers = {};
+  blobServiceClient;
+  options = {};
+  constructor() {
+    this.blobServiceClient = BlobServiceClient.fromConnectionString(
+      this.env.AZ_STORAGE_CONNECTION_STRING,
+      this.storagePipelineOptions()
+    );
+  }
+  storagePipelineOptions() {
+    return {};
+  }
+  async createContainer(containerName) {
+    if (this.containers[containerName]) {
+      return this.containers[containerName];
+    }
+    const container = await this.createContainerClient(containerName);
+    this.containers[containerName] = container;
+    return container;
+  }
+  async upload(bucketName, file2, fileId) {
+    fileId ??= this.createId();
+    const block = this.getBlock(bucketName, fileId);
+    const metadata = {
+      name: file2.name,
+      type: file2.type
+    };
+    if (file2.filepath) {
+      await block.uploadFile(file2.filepath, {
+        metadata,
+        blobHTTPHeaders: {
+          blobContentType: file2.type
+        }
+      });
+    } else if (file2.size > 0) {
+      await block.uploadData(await file2.arrayBuffer(), {
+        metadata,
+        blobHTTPHeaders: {
+          blobContentType: file2.type
+        }
+      });
+    } else {
+      throw new Error("Raw stream upload is not supported yet");
+    }
+    return fileId;
+  }
+  async download(bucketName, fileId) {
+    const block = this.getBlock(bucketName, fileId);
+    const blob = await block.download().catch((error) => {
+      if (error instanceof Error) {
+        throw new FileNotFoundError("Error downloading file", { cause: error });
+      }
+      throw error;
+    });
+    if (!blob.readableStreamBody) {
+      throw new FileNotFoundError("File not found - empty stream body");
+    }
+    return file(blob.readableStreamBody, blob.metadata);
+  }
+  async exists(bucketName, fileId) {
+    return await this.getBlock(bucketName, fileId).exists();
+  }
+  async delete(bucketName, fileId) {
+    try {
+      await this.getBlock(bucketName, fileId).delete();
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new FileNotFoundError("Error deleting file", { cause: error });
+      }
+      throw error;
+    }
+  }
+  getBlock(container, fileId) {
+    if (!this.containers[container]) {
+      throw new FileNotFoundError(
+        `File '${fileId}' not found - container '${container}' does not exists`
+      );
+    }
+    return this.containers[container].getBlockBlobClient(fileId);
+  }
+  onStart = $hook({
+    name: "start",
+    handler: async () => {
+      for (const bucket of this.bucketProvider.getBuckets()) {
+        const containerName = bucket.name.replaceAll("/", "-").toLowerCase();
+        this.log.debug(`Prepare container ${containerName}...`);
+        if (!this.containers[containerName]) {
+          this.containers[containerName] = await this.createContainerClient(containerName);
+        }
+        this.log.info(`Container ${bucket} OK`);
+      }
+    }
+  });
+  async createContainerClient(name) {
+    const container = this.blobServiceClient.getContainerClient(name);
+    await this.dateTimeProvider.deadline(
+      (abortSignal) => container.createIfNotExists({ abortSignal }),
+      { seconds: 5 }
+    );
+    return container;
+  }
+  createId() {
+    return randomUUID();
+  }
+}
+
+class AzureBucketModule {
+  name = "alepha/bucket/azure";
+  alepha = $inject(Alepha);
+  constructor() {
+    this.alepha.with(
+      {
+        default: true,
+        provide: FileStorageProvider,
+        use: AzureFileStorageProvider
+      },
+      BucketModule
+    );
+  }
+}
+
+export { AzureBucketModule, AzureFileStorageProvider };

package/package.json

@@ -0,0 +1,49 @@
+{
+	"name": "@alepha/bucket-azure",
+	"keywords": [
+		"alepha",
+		"bucket",
+		"file-storage",
+		"file",
+		"azure",
+		"storage-blob"
+	],
+	"author": "Feunard",
+	"version": "0.7.1",
+	"type": "module",
+	"license": "MIT",
+	"main": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"files": [
+		"dist",
+		"src"
+	],
+	"dependencies": {
+		"@alepha/bucket": "0.7.1",
+		"@alepha/core": "0.7.1",
+		"@alepha/datetime": "0.7.1",
+		"@alepha/file": "0.7.1",
+		"@azure/storage-blob": "^12.27.0"
+	},
+	"devDependencies": {
+		"pkgroll": "^2.13.1",
+		"vitest": "^3.2.4"
+	},
+	"scripts": {
+		"test": "vitest run",
+		"build": "pkgroll --clean-dist"
+	},
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/feunard/alepha.git"
+	},
+	"homepage": "https://github.com/feunard/alepha",
+	"module": "./dist/index.js",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	}
+}

package/src/index.ts

@@ -0,0 +1,22 @@
+import { BucketModule, FileStorageProvider } from "@alepha/bucket";
+import { $inject, Alepha, type Module } from "@alepha/core";
+import { AzureFileStorageProvider } from "./providers/AzureFileStorageProvider.ts";
+
+export * from "./providers/AzureFileStorageProvider.ts";
+
+export class AzureBucketModule implements Module {
+	public readonly name = "alepha/bucket/azure";
+
+	protected readonly alepha = $inject(Alepha);
+
+	constructor() {
+		this.alepha.with(
+			{
+				default: true,
+				provide: FileStorageProvider,
+				use: AzureFileStorageProvider,
+			},
+			BucketModule,
+		);
+	}
+}

package/src/providers/AzureFileStorageProvider.ts

@@ -0,0 +1,174 @@
+import { randomUUID } from "node:crypto";
+import {
+	BucketDescriptorProvider,
+	FileNotFoundError,
+	type FileStorageProvider,
+} from "@alepha/bucket";
+import type { Static } from "@alepha/core";
+import { $env, $hook, $inject, $logger, type FileLike, t } from "@alepha/core";
+import { DateTimeProvider } from "@alepha/datetime";
+import { file } from "@alepha/file";
+import {
+	BlobServiceClient,
+	type BlockBlobClient,
+	type ContainerClient,
+	type StoragePipelineOptions,
+} from "@azure/storage-blob";
+
+const envSchema = t.object({
+	AZ_STORAGE_CONNECTION_STRING: t.string({
+		size: "long",
+		default:
+			"DefaultEndpointsProtocol=http;" +
+			"AccountName=devstoreaccount1;" +
+			"AccountKey=Eby8vdM02xNOcqFlqUwJPLlmEtlCDXJ1OUzFT50uSRZ6IFsuFq2UVErCz4I6tq/K1SZFPTOtr/KBHBeksoGMGw==;" +
+			"BlobEndpoint=http://127.0.0.1:10000/devstoreaccount1;",
+	}),
+});
+
+declare module "@alepha/core" {
+	interface Env extends Partial<Static<typeof envSchema>> {}
+}
+
+export class AzureFileStorageProvider implements FileStorageProvider {
+	protected readonly log = $logger();
+	protected readonly env = $env(envSchema);
+	protected readonly bucketProvider = $inject(BucketDescriptorProvider);
+	protected readonly dateTimeProvider = $inject(DateTimeProvider);
+	protected readonly containers: Record<string, ContainerClient> = {};
+	protected readonly blobServiceClient: BlobServiceClient;
+	protected readonly options: StoragePipelineOptions = {};
+
+	constructor() {
+		this.blobServiceClient = BlobServiceClient.fromConnectionString(
+			this.env.AZ_STORAGE_CONNECTION_STRING,
+			this.storagePipelineOptions(),
+		);
+	}
+
+	public storagePipelineOptions(): StoragePipelineOptions {
+		return {};
+	}
+
+	public async createContainer(
+		containerName: string,
+	): Promise<ContainerClient> {
+		if (this.containers[containerName]) {
+			return this.containers[containerName];
+		}
+		const container = await this.createContainerClient(containerName);
+		this.containers[containerName] = container;
+		return container;
+	}
+
+	public async upload(
+		bucketName: string,
+		file: FileLike,
+		fileId?: string,
+	): Promise<string> {
+		fileId ??= this.createId();
+		const block = this.getBlock(bucketName, fileId);
+
+		const metadata = {
+			name: file.name,
+			type: file.type,
+		};
+
+		if (file.filepath) {
+			await block.uploadFile(file.filepath, {
+				metadata,
+				blobHTTPHeaders: {
+					blobContentType: file.type,
+				},
+			});
+		} else if (file.size > 0) {
+			await block.uploadData(await file.arrayBuffer(), {
+				metadata,
+				blobHTTPHeaders: {
+					blobContentType: file.type,
+				},
+			});
+		} else {
+			throw new Error("Raw stream upload is not supported yet");
+		}
+
+		return fileId;
+	}
+
+	public async download(bucketName: string, fileId: string): Promise<FileLike> {
+		const block = this.getBlock(bucketName, fileId);
+
+		const blob = await block.download().catch((error) => {
+			if (error instanceof Error) {
+				throw new FileNotFoundError("Error downloading file", { cause: error });
+			}
+
+			throw error;
+		});
+
+		if (!blob.readableStreamBody) {
+			throw new FileNotFoundError("File not found - empty stream body");
+		}
+
+		return file(blob.readableStreamBody, blob.metadata);
+	}
+
+	public async exists(bucketName: string, fileId: string): Promise<boolean> {
+		return await this.getBlock(bucketName, fileId).exists();
+	}
+
+	public async delete(bucketName: string, fileId: string): Promise<void> {
+		try {
+			await this.getBlock(bucketName, fileId).delete();
+		} catch (error) {
+			if (error instanceof Error) {
+				throw new FileNotFoundError("Error deleting file", { cause: error });
+			}
+			throw error;
+		}
+	}
+
+	public getBlock(container: string, fileId: string): BlockBlobClient {
+		if (!this.containers[container]) {
+			throw new FileNotFoundError(
+				`File '${fileId}' not found - container '${container}' does not exists`,
+			);
+		}
+
+		return this.containers[container].getBlockBlobClient(fileId);
+	}
+
+	public readonly onStart = $hook({
+		name: "start",
+		handler: async () => {
+			for (const bucket of this.bucketProvider.getBuckets()) {
+				const containerName = bucket.name.replaceAll("/", "-").toLowerCase();
+				this.log.debug(`Prepare container ${containerName}...`);
+
+				if (!this.containers[containerName]) {
+					this.containers[containerName] =
+						await this.createContainerClient(containerName);
+				}
+
+				this.log.info(`Container ${bucket} OK`);
+			}
+		},
+	});
+
+	protected async createContainerClient(
+		name: string,
+	): Promise<ContainerClient> {
+		const container = this.blobServiceClient.getContainerClient(name);
+
+		await this.dateTimeProvider.deadline(
+			(abortSignal) => container.createIfNotExists({ abortSignal }),
+			{ seconds: 5 },
+		);
+
+		return container;
+	}
+
+	protected createId(): string {
+		return randomUUID();
+	}
+}