nest-unstorage 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Tankosin
+
+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,67 @@
+# nest-unstorage
+
+[![npm version][npm-version-src]][npm-version-href]
+[![npm downloads][npm-downloads-src]][npm-downloads-href]
+[![License][license-src]][license-href]
+
+Type-safe [unstorage](https://unstorage.unjs.io/) integration for [NestJS](https://nestjs.com/) with an injectable, driver-based key-value storage.
+
+## Install
+
+```sh
+pnpm add nest-unstorage unstorage
+```
+
+## Usage
+
+```ts
+import { Module } from '@nestjs/common'
+import { StorageModule } from 'nest-unstorage'
+
+@Module({
+  imports: [
+    StorageModule.forRoot({
+      driver: { driver: 'redis', url: process.env.REDIS_URL },
+    }),
+  ],
+})
+export class AppModule {}
+```
+
+```ts
+import type { Storage } from 'unstorage'
+import { Injectable } from '@nestjs/common'
+import { InjectStorage } from 'nest-unstorage'
+
+@Injectable()
+export class TokenService {
+  constructor(@InjectStorage() private readonly storage: Storage) {}
+}
+```
+
+Built-in drivers load on demand; install their peer deps (`ioredis` for `redis`).
+
+### Async
+
+```ts
+StorageModule.forRootAsync({
+  imports: [ConfigModule],
+  inject: [ConfigService],
+  useFactory: (config: ConfigService) => ({
+    driver: { driver: 'redis', url: config.getOrThrow('REDIS_URL') },
+  }),
+})
+```
+
+## License
+
+[MIT](./LICENSE) License © [Tankosin](https://github.com/tankosin)
+
+<!-- Badges -->
+
+[npm-version-src]: https://npmx.dev/api/registry/badge/version/nest-unstorage
+[npm-version-href]: https://npmx.dev/package/nest-unstorage
+[npm-downloads-src]: https://npmx.dev/api/registry/badge/downloads/nest-unstorage
+[npm-downloads-href]: https://npmx.dev/package/nest-unstorage
+[license-src]: https://img.shields.io/npm/l/nest-unstorage?style=flat&colorA=080f12&colorB=1fa669
+[license-href]: ./LICENSE

package/dist/index.cjs

@@ -0,0 +1,116 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _nestjs_common = require("@nestjs/common");
+let unstorage = require("unstorage");
+//#region src/storage.constants.ts
+/** Injection token for the root unstorage `Storage` instance. */
+const STORAGE = "nest-unstorage:storage";
+//#endregion
+//#region src/storage.decorators.ts
+/** Property/parameter decorator that injects the {@link STORAGE} instance. */
+function InjectStorage() {
+	return (0, _nestjs_common.Inject)(STORAGE);
+}
+//#endregion
+//#region src/storage.module-definition.ts
+const { ConfigurableModuleClass, MODULE_OPTIONS_TOKEN, OPTIONS_TYPE, ASYNC_OPTIONS_TYPE } = new _nestjs_common.ConfigurableModuleBuilder({ moduleName: "Storage" }).setClassMethodName("forRoot").setExtras({ isGlobal: true }, (definition, extras) => ({
+	...definition,
+	global: extras.isGlobal
+})).build();
+//#endregion
+//#region src/storage.factory.ts
+function isMountConfig(config) {
+	return typeof config.driver === "string";
+}
+async function resolveDriver(config) {
+	if (!isMountConfig(config)) return config;
+	const { driver, ...options } = config;
+	const specifier = unstorage.builtinDrivers[driver] ?? driver;
+	let module;
+	try {
+		module = await import(specifier);
+	} catch (cause) {
+		throw new Error(`[nest-unstorage] Failed to load driver "${driver}". Install its peer dependency if it is a built-in driver.`, { cause });
+	}
+	const factory = module.default ?? module;
+	if (typeof factory !== "function") throw new TypeError(`[nest-unstorage] Driver "${driver}" did not resolve to a factory function.`);
+	return factory(options);
+}
+async function createStorageInstance(options) {
+	const mounts = Object.entries(options.mounts ?? {});
+	const [rootDriver, mountDrivers] = await Promise.all([options.driver ? resolveDriver(options.driver) : Promise.resolve(void 0), Promise.all(mounts.map(async ([, config]) => resolveDriver(config)))]);
+	const storage = (0, unstorage.createStorage)({ driver: rootDriver });
+	mounts.forEach(([base], index) => storage.mount(base, mountDrivers[index]));
+	return storage;
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.135.0/helpers/esm/decorateMetadata.js
+function __decorateMetadata(k, v) {
+	if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.135.0/helpers/esm/decorateParam.js
+function __decorateParam(paramIndex, decorator) {
+	return function(target, key) {
+		decorator(target, key, paramIndex);
+	};
+}
+//#endregion
+//#region \0@oxc-project+runtime@0.135.0/helpers/esm/decorate.js
+function __decorate(decorators, target, key, desc) {
+	var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+	if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+	else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+	return c > 3 && r && Object.defineProperty(target, key, r), r;
+}
+//#endregion
+//#region src/storage.providers.ts
+const storageProvider = {
+	provide: STORAGE,
+	useFactory: createStorageInstance,
+	inject: [MODULE_OPTIONS_TOKEN]
+};
+let StorageDisposer = class StorageDisposer {
+	storage;
+	constructor(storage) {
+		this.storage = storage;
+	}
+	async onApplicationShutdown() {
+		await this.storage.dispose();
+	}
+};
+StorageDisposer = __decorate([
+	(0, _nestjs_common.Injectable)(),
+	__decorateParam(0, (0, _nestjs_common.Inject)(STORAGE)),
+	__decorateMetadata("design:paramtypes", [Object])
+], StorageDisposer);
+//#endregion
+//#region src/storage.module.ts
+let StorageModule = class StorageModule extends ConfigurableModuleClass {
+	static forRoot(options) {
+		return this.withStorage(super.forRoot(options));
+	}
+	static forRootAsync(options) {
+		return this.withStorage(super.forRootAsync(options));
+	}
+	static withStorage(definition) {
+		return {
+			...definition,
+			providers: [
+				...definition.providers ?? [],
+				storageProvider,
+				StorageDisposer
+			],
+			exports: [...definition.exports ?? [], STORAGE]
+		};
+	}
+};
+StorageModule = __decorate([(0, _nestjs_common.Module)({})], StorageModule);
+//#endregion
+exports.InjectStorage = InjectStorage;
+exports.STORAGE = STORAGE;
+Object.defineProperty(exports, "StorageModule", {
+	enumerable: true,
+	get: function() {
+		return StorageModule;
+	}
+});

package/dist/index.d.cts

@@ -0,0 +1,48 @@
+import { DynamicModule } from "@nestjs/common";
+import { BuiltinDriverName, BuiltinDriverOptions, Driver } from "unstorage";
+
+//#region src/storage.constants.d.ts
+/** Injection token for the root unstorage `Storage` instance. */
+declare const STORAGE = "nest-unstorage:storage";
+//#endregion
+//#region src/storage.decorators.d.ts
+/** Property/parameter decorator that injects the {@link STORAGE} instance. */
+declare function InjectStorage(): PropertyDecorator & ParameterDecorator;
+//#endregion
+//#region src/storage.types.d.ts
+type OptionsFor<Name extends BuiltinDriverName> = Name extends keyof BuiltinDriverOptions ? BuiltinDriverOptions[Name] : unknown;
+/**
+ * A built-in driver referenced by name with its options inlined and type-checked
+ * (e.g. `{ driver: 'fs', base: './data' }`).
+ */
+type BuiltinMountConfig = { [Name in BuiltinDriverName]: {
+  driver: Name;
+} & OptionsFor<Name> }[BuiltinDriverName];
+/**
+ * A mount's driver: a built-in referenced by name ({@link BuiltinMountConfig}) or a
+ * `Driver` instance (e.g. `memoryDriver()`).
+ */
+type StorageDriverConfig = Driver | BuiltinMountConfig;
+/** Options for {@link StorageModule.forRoot}. */
+interface StorageModuleOptions {
+  /** Root driver for unprefixed keys. Defaults to an in-memory driver. */
+  driver?: StorageDriverConfig;
+  /** Mountpoints keyed by base, each routed to its own driver. */
+  mounts?: Record<string, StorageDriverConfig>;
+}
+//#endregion
+//#region src/storage.module-definition.d.ts
+interface StorageModuleExtraOptions {
+  /** Register the module globally. Defaults to `true`. */
+  isGlobal?: boolean;
+}
+declare const ConfigurableModuleClass: import("@nestjs/common").ConfigurableModuleCls<StorageModuleOptions, "forRoot", "create", StorageModuleExtraOptions>, MODULE_OPTIONS_TOKEN: string | symbol, OPTIONS_TYPE: StorageModuleOptions & Partial<StorageModuleExtraOptions>, ASYNC_OPTIONS_TYPE: import("@nestjs/common").ConfigurableModuleAsyncOptions<StorageModuleOptions, "create"> & Partial<StorageModuleExtraOptions>;
+//#endregion
+//#region src/storage.module.d.ts
+declare class StorageModule extends ConfigurableModuleClass {
+  static forRoot(options: typeof OPTIONS_TYPE): DynamicModule;
+  static forRootAsync(options: typeof ASYNC_OPTIONS_TYPE): DynamicModule;
+  private static withStorage;
+}
+//#endregion
+export { type BuiltinMountConfig, InjectStorage, STORAGE, type StorageDriverConfig, StorageModule, type StorageModuleOptions };

package/package.json

@@ -0,0 +1,89 @@
+{
+  "name": "nest-unstorage",
+  "type": "module",
+  "version": "0.0.1",
+  "description": "Type-safe unstorage integration for NestJS with an injectable, driver-based key-value storage.",
+  "author": "Tankosin <tankosinn@gmail.com>",
+  "license": "MIT",
+  "homepage": "https://github.com/tankosin/nest-unstorage#readme",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/tankosin/nest-unstorage.git"
+  },
+  "bugs": {
+    "url": "https://github.com/tankosin/nest-unstorage/issues"
+  },
+  "keywords": [
+    "nestjs",
+    "nest",
+    "unstorage",
+    "unjs",
+    "nitro",
+    "storage",
+    "key-value",
+    "kv",
+    "cache",
+    "driver",
+    "dynamic-module"
+  ],
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.cts",
+      "default": "./dist/index.cjs"
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "types": "./dist/index.d.cts",
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=18.12.0"
+  },
+  "peerDependencies": {
+    "@nestjs/common": "^10.0.0 || ^11.0.0",
+    "reflect-metadata": "^0.1.13 || ^0.2.0",
+    "unstorage": "^1.10.0"
+  },
+  "devDependencies": {
+    "@antfu/eslint-config": "9.0.0",
+    "@nestjs/common": "11.1.26",
+    "@nestjs/core": "11.1.26",
+    "@nestjs/testing": "11.1.26",
+    "@types/node": "25.9.3",
+    "@vitest/coverage-v8": "4.1.8",
+    "bumpp": "11.1.0",
+    "eslint": "10.4.1",
+    "installed-check": "10.0.1",
+    "lint-staged": "17.0.7",
+    "reflect-metadata": "0.2.2",
+    "rxjs": "7.8.2",
+    "simple-git-hooks": "2.13.1",
+    "tsdown": "0.22.2",
+    "tsx": "4.22.4",
+    "typescript": "6.0.3",
+    "unstorage": "1.17.5",
+    "vitest": "4.1.8"
+  },
+  "simple-git-hooks": {
+    "pre-commit": "pnpm lint-staged"
+  },
+  "lint-staged": {
+    "*": "eslint --cache --fix"
+  },
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "lint": "eslint --cache .",
+    "lint:fix": "eslint --cache --fix .",
+    "test": "vitest run",
+    "test:cov": "vitest run --coverage",
+    "test:e2e": "vitest run --project e2e",
+    "test:unit": "vitest run --project unit",
+    "typecheck": "tsc --noEmit",
+    "publish:ci": "tsx scripts/publish.ts",
+    "release": "bumpp"
+  }
+}