@poppinss/utils 7.0.0-next.3 → 7.0.0-next.5

package/README.md

@@ -627,6 +627,123 @@ const rawValue = secret.release()
 rawValue === opaque_raw_token // true
 ```
 
+## ImportsBag
+
+The `ImportsBag` class helps you manage and deduplicate import statements when generating code. It automatically merges imports from the same source and generates properly formatted import statements.
+
+This is particularly useful when building code generators, AST transformers, or any tool that needs to collect and output import statements.
+
+```ts
+import { ImportsBag } from '@poppinss/utils'
+
+const bag = new ImportsBag()
+
+// Add named imports
+bag.add({
+  source: 'lodash',
+  namedImports: ['debounce'],
+})
+
+// Add more imports from the same source - they will be merged
+bag.add({
+  source: 'lodash',
+  namedImports: ['throttle', 'debounce'], // duplicate "debounce" will be removed
+})
+
+// Add default import with named imports
+bag.add({
+  source: 'react',
+  defaultImport: 'React',
+  namedImports: ['useState', 'useEffect'],
+})
+
+// Add type imports
+bag.add({
+  source: 'express',
+  typeImports: ['Request', 'Response'],
+})
+
+// Generate import statements
+console.log(bag.toString())
+// import { debounce, throttle } from 'lodash'
+// import React, { useState, useEffect } from 'react'
+// import type { Request, Response } from 'express'
+```
+
+### Import Types
+
+The `ImportsBag` supports three types of imports:
+
+- **Default imports**: `defaultImport: 'React'` generates `import React from 'react'`
+- **Named imports**: `namedImports: ['useState']` generates `import { useState } from 'react'`
+- **Type imports**: `typeImports: ['FC']` generates `import type { FC } from 'react'`
+
+You can combine default and named imports in a single statement, but type imports are always generated as separate statements.
+
+```ts
+bag.add({
+  source: 'react',
+  defaultImport: 'React',
+  namedImports: ['useState'],
+  typeImports: ['FC'],
+})
+
+console.log(bag.toString())
+// import React, { useState } from 'react'
+// import type { FC } from 'react'
+```
+
+### Deduplication
+
+The `ImportsBag` automatically deduplicates imports from the same source:
+
+- Named and type imports are deduplicated when calling `toArray()` or `toString()`
+- Default imports are replaced (the last one wins)
+- Imports are merged by source, so multiple `add()` calls for the same source will combine all imports
+
+```ts
+bag.add({ source: 'lodash', namedImports: ['debounce'] })
+bag.add({ source: 'lodash', namedImports: ['throttle'] })
+bag.add({ source: 'lodash', namedImports: ['debounce'] }) // duplicate
+
+console.log(bag.toString())
+// import { debounce, throttle } from 'lodash'
+```
+
+### Methods
+
+#### add(importInfo)
+
+Add an import to the bag. Returns `this` for method chaining.
+
+```ts
+bag
+  .add({ source: 'lodash', namedImports: ['debounce'] })
+  .add({ source: 'express', typeImports: ['Request'] })
+```
+
+#### toArray()
+
+Returns an array of deduplicated `ImportInfo` objects.
+
+```ts
+const imports = bag.toArray()
+// [
+//   { source: 'lodash', defaultImport: undefined, namedImports: ['debounce'], typeImports: undefined },
+//   { source: 'express', defaultImport: undefined, namedImports: undefined, typeImports: ['Request'] }
+// ]
+```
+
+#### toString()
+
+Generates formatted import statements as a string.
+
+```ts
+const code = bag.toString()
+// import { debounce } from 'lodash'
+// import type { Request } from 'express'
+```
+
 [gh-workflow-image]: https://img.shields.io/github/actions/workflow/status/poppinss/utils/checks.yml?style=for-the-badge
 [gh-workflow-url]: https://github.com/poppinss/utils/actions/workflows/checks.yml 'Github action'
 [typescript-image]: https://img.shields.io/badge/Typescript-294E80.svg?style=for-the-badge&logo=typescript

package/build/chunk-BNZ4_A-W.js

@@ -0,0 +1,23 @@
+import "node:module";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __commonJSMin = (cb, mod) => () => (mod || cb((mod = { exports: {} }).exports, mod), mod.exports);
+var __copyProps = (to, from, except, desc) => {
+	if (from && typeof from === "object" || typeof from === "function") for (var keys = __getOwnPropNames(from), i = 0, n = keys.length, key; i < n; i++) {
+		key = keys[i];
+		if (!__hasOwnProp.call(to, key) && key !== except) __defProp(to, key, {
+			get: ((k) => from[k]).bind(null, key),
+			enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable
+		});
+	}
+	return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", {
+	value: mod,
+	enumerable: true
+}) : target, mod));
+export { __toESM as n, __commonJSMin as t };

package/build/exception-L7vjh-Gv.js

@@ -0,0 +1,2 @@
+import { Exception, InvalidArgumentsException, RuntimeException, createError } from "@poppinss/exception";
+export { createError as i, InvalidArgumentsException as n, RuntimeException as r, Exception as t };

package/build/index.d.ts

@@ -6,4 +6,5 @@ export { naturalSort } from './src/natural_sort.js';
 export { isScriptFile } from './src/is_script_file.js';
 export { importDefault } from './src/import_default.js';
 export { MessageBuilder } from './src/message_builder.js';
+export { ImportsBag, type ImportInfo } from './src/imports_bag.js';
 export { defineStaticProperty } from './src/define_static_property.js';

package/build/index.js

@@ -1,179 +1,154 @@
-import {
-  RuntimeException
-} from "./chunk-SKNTF5Q5.js";
-import {
-  isScriptFile,
-  naturalSort
-} from "./chunk-XFX47BKO.js";
-import {
-  safeParse,
-  safeStringify
-} from "./chunk-YFSCSJNE.js";
-
-// src/secret.ts
-var REDACTED = "[redacted]";
-var Secret = class _Secret {
-  /** The secret value */
-  #value;
-  #keyword;
-  constructor(value, redactedKeyword) {
-    this.#value = value;
-    this.#keyword = redactedKeyword || REDACTED;
-  }
-  toJSON() {
-    return this.#keyword;
-  }
-  valueOf() {
-    return this.#keyword;
-  }
-  [Symbol.for("nodejs.util.inspect.custom")]() {
-    return this.#keyword;
-  }
-  toLocaleString() {
-    return this.#keyword;
-  }
-  toString() {
-    return this.#keyword;
-  }
-  /**
-   * Returns the original value
-   */
-  release() {
-    return this.#value;
-  }
-  /**
-   * Transform the original value and create a new
-   * secret from it.
-   */
-  map(transformFunc) {
-    return new _Secret(transformFunc(this.#value));
-  }
+import { n as __toESM } from "./chunk-BNZ4_A-W.js";
+import { n as isScriptFile, r as naturalSort, t as require_main } from "./main-CdreHl1_.js";
+import { r as RuntimeException } from "./exception-L7vjh-Gv.js";
+import { n as safeParse, t as safeStringify } from "./main-aO4h7ygK.js";
+import { flattie } from "flattie";
+import { Buffer } from "node:buffer";
+import { timingSafeEqual } from "node:crypto";
+import string from "@poppinss/string";
+const REDACTED = "[redacted]";
+var Secret = class Secret {
+	#value;
+	#keyword;
+	constructor(value, redactedKeyword) {
+		this.#value = value;
+		this.#keyword = redactedKeyword || REDACTED;
+	}
+	toJSON() {
+		return this.#keyword;
+	}
+	valueOf() {
+		return this.#keyword;
+	}
+	[Symbol.for("nodejs.util.inspect.custom")]() {
+		return this.#keyword;
+	}
+	toLocaleString() {
+		return this.#keyword;
+	}
+	toString() {
+		return this.#keyword;
+	}
+	release() {
+		return this.#value;
+	}
+	map(transformFunc) {
+		return new Secret(transformFunc(this.#value));
+	}
 };
-
-// src/compose.ts
 function compose(superclass, ...mixins) {
-  return mixins.reduce((c, mixin) => mixin(c), superclass);
+	return mixins.reduce((c, mixin) => mixin(c), superclass);
 }
-
-// src/flatten.ts
-import { flattie } from "flattie";
 function flatten(input, glue, keepNullish) {
-  return flattie(input, glue, keepNullish);
+	return flattie(input, glue, keepNullish);
 }
-
-// src/safe_equal.ts
-import { Buffer } from "buffer";
-import { timingSafeEqual } from "crypto";
 function safeEqual(trustedValue, userInput) {
-  if (typeof trustedValue === "string" && typeof userInput === "string") {
-    const trustedLength = Buffer.byteLength(trustedValue);
-    const trustedValueBuffer = Buffer.alloc(trustedLength, 0, "utf-8");
-    trustedValueBuffer.write(trustedValue);
-    const userValueBuffer = Buffer.alloc(trustedLength, 0, "utf-8");
-    userValueBuffer.write(userInput);
-    return timingSafeEqual(trustedValueBuffer, userValueBuffer) && trustedLength === Buffer.byteLength(userInput);
-  }
-  return timingSafeEqual(
-    Buffer.from(trustedValue),
-    Buffer.from(userInput)
-  );
+	if (typeof trustedValue === "string" && typeof userInput === "string") {
+		const trustedLength = Buffer.byteLength(trustedValue);
+		const trustedValueBuffer = Buffer.alloc(trustedLength, 0, "utf-8");
+		trustedValueBuffer.write(trustedValue);
+		const userValueBuffer = Buffer.alloc(trustedLength, 0, "utf-8");
+		userValueBuffer.write(userInput);
+		return timingSafeEqual(trustedValueBuffer, userValueBuffer) && trustedLength === Buffer.byteLength(userInput);
+	}
+	return timingSafeEqual(Buffer.from(trustedValue), Buffer.from(userInput));
 }
-
-// src/import_default.ts
 async function importDefault(importFn, filePath) {
-  const moduleExports = await importFn();
-  if (!("default" in moduleExports)) {
-    const errorMessage = filePath ? `Missing "export default" in module "${filePath}"` : `Missing "export default" from lazy import "${importFn}"`;
-    throw new RuntimeException(errorMessage, {
-      cause: {
-        source: importFn
-      }
-    });
-  }
-  return moduleExports.default;
+	const moduleExports = await importFn();
+	if (!("default" in moduleExports)) throw new RuntimeException(filePath ? `Missing "export default" in module "${filePath}"` : `Missing "export default" from lazy import "${importFn}"`, { cause: { source: importFn } });
+	return moduleExports.default;
 }
-
-// src/message_builder.ts
-import string from "@poppinss/string";
 var MessageBuilder = class {
-  #getExpiryDate(expiresIn) {
-    if (!expiresIn) {
-      return void 0;
-    }
-    const expiryMs = string.milliseconds.parse(expiresIn);
-    return new Date(Date.now() + expiryMs);
-  }
-  /**
-   * Returns a boolean telling, if message has been expired or not
-   */
-  #isExpired(message) {
-    if (!message.expiryDate) {
-      return false;
-    }
-    const expiryDate = new Date(message.expiryDate);
-    return Number.isNaN(expiryDate.getTime()) || expiryDate < /* @__PURE__ */ new Date();
-  }
-  /**
-   * Builds a message by encoding expiry date and purpose inside it.
-   */
-  build(message, expiresIn, purpose) {
-    const expiryDate = this.#getExpiryDate(expiresIn);
-    return safeStringify({ message, purpose, expiryDate });
-  }
-  /**
-   * Verifies the message for expiry and purpose.
-   */
-  verify(message, purpose) {
-    const parsed = safeParse(message);
-    if (typeof parsed !== "object" || !parsed) {
-      return null;
-    }
-    if (!parsed.message) {
-      return null;
-    }
-    if (parsed.purpose !== purpose) {
-      return null;
-    }
-    if (this.#isExpired(parsed)) {
-      return null;
-    }
-    return parsed.message;
-  }
+	#getExpiryDate(expiresIn) {
+		if (!expiresIn) return;
+		const expiryMs = string.milliseconds.parse(expiresIn);
+		return new Date(Date.now() + expiryMs);
+	}
+	#isExpired(message) {
+		if (!message.expiryDate) return false;
+		const expiryDate = new Date(message.expiryDate);
+		return Number.isNaN(expiryDate.getTime()) || expiryDate < /* @__PURE__ */ new Date();
+	}
+	build(message, expiresIn, purpose) {
+		return safeStringify({
+			message,
+			purpose,
+			expiryDate: this.#getExpiryDate(expiresIn)
+		});
+	}
+	verify(message, purpose) {
+		const parsed = safeParse(message);
+		if (typeof parsed !== "object" || !parsed) return null;
+		if (!parsed.message) return null;
+		if (parsed.purpose !== purpose) return null;
+		if (this.#isExpired(parsed)) return null;
+		return parsed.message;
+	}
 };
-
-// src/define_static_property.ts
-import lodash from "@poppinss/utils/lodash";
-function defineStaticProperty(self, propertyName, {
-  initialValue,
-  strategy
-}) {
-  if (!self.hasOwnProperty(propertyName)) {
-    const value = self[propertyName];
-    if (strategy === "define" || value === void 0) {
-      Object.defineProperty(self, propertyName, {
-        value: initialValue,
-        configurable: true,
-        enumerable: true,
-        writable: true
-      });
-      return;
-    }
-    Object.defineProperty(self, propertyName, {
-      value: typeof strategy === "function" ? strategy(value) : lodash.cloneDeep(value),
-      configurable: true,
-      enumerable: true,
-      writable: true
-    });
-  }
-}
-export {
-  MessageBuilder,
-  Secret,
-  compose,
-  defineStaticProperty,
-  flatten,
-  importDefault,
-  isScriptFile,
-  naturalSort,
-  safeEqual
+var ImportsBag = class {
+	#imports = /* @__PURE__ */ new Map();
+	#generateImportStatement(imp) {
+		const parts = [];
+		if (imp.defaultImport || imp.namedImports && imp.namedImports.length > 0) {
+			const importParts = [];
+			if (imp.defaultImport) importParts.push(imp.defaultImport);
+			if (imp.namedImports && imp.namedImports.length > 0) importParts.push(`{ ${imp.namedImports.join(", ")} }`);
+			parts.push(`import ${importParts.join(", ")} from '${imp.source}'`);
+		}
+		if (imp.typeImports && imp.typeImports.length > 0) parts.push(`import type { ${imp.typeImports.join(", ")} } from '${imp.source}'`);
+		return parts.join("\n");
+	}
+	add(importInfo) {
+		const existing = this.#imports.get(importInfo.source);
+		if (existing) {
+			if (importInfo.defaultImport) existing.defaultImport = importInfo.defaultImport;
+			if (importInfo.namedImports) {
+				if (!existing.namedImports) existing.namedImports = [];
+				existing.namedImports.push(...importInfo.namedImports);
+			}
+			if (importInfo.typeImports) {
+				if (!existing.typeImports) existing.typeImports = [];
+				existing.typeImports.push(...importInfo.typeImports);
+			}
+		} else this.#imports.set(importInfo.source, {
+			source: importInfo.source,
+			defaultImport: importInfo.defaultImport,
+			namedImports: importInfo.namedImports ? [...importInfo.namedImports] : void 0,
+			typeImports: importInfo.typeImports ? [...importInfo.typeImports] : void 0
+		});
+		return this;
+	}
+	toArray() {
+		return Array.from(this.#imports.values()).map((imp) => ({
+			source: imp.source,
+			defaultImport: imp.defaultImport,
+			namedImports: imp.namedImports ? [...new Set(imp.namedImports)] : void 0,
+			typeImports: imp.typeImports ? [...new Set(imp.typeImports)] : void 0
+		}));
+	}
+	toString() {
+		return this.toArray().map((imp) => this.#generateImportStatement(imp)).join("\n");
+	}
 };
+var import_main = /* @__PURE__ */ __toESM(require_main());
+function defineStaticProperty(self, propertyName, { initialValue, strategy }) {
+	if (!self.hasOwnProperty(propertyName)) {
+		const value = self[propertyName];
+		if (strategy === "define" || value === void 0) {
+			Object.defineProperty(self, propertyName, {
+				value: initialValue,
+				configurable: true,
+				enumerable: true,
+				writable: true
+			});
+			return;
+		}
+		Object.defineProperty(self, propertyName, {
+			value: typeof strategy === "function" ? strategy(value) : import_main.default.cloneDeep(value),
+			configurable: true,
+			enumerable: true,
+			writable: true
+		});
+	}
+}
+export { ImportsBag, MessageBuilder, Secret, compose, defineStaticProperty, flatten, importDefault, isScriptFile, naturalSort, safeEqual };