@ssets/dts 1.0.0

package/README.md

@@ -0,0 +1,88 @@
+# @ssets/dts
+
+Simple and focuses on the action of merging multiple TypeScript declaration files (.d.ts) into one.
+
+## Installation
+
+Install the package as a development dependency:
+
+```bash
+npm install @ssets/dts --save-dev
+# or using yarn
+yarn add @ssets/dts --dev
+# or using pnpm
+pnpm add -D @ssets/dts
+```
+
+## Usage
+
+You can use the `generateDtsBundle` function to compile and bundle your declaration files. It accepts an array of entry points and optional compilation configuration.
+
+```ts
+import { generateDtsBundle } from "@ssets/dts";
+import * as fs from "fs";
+
+const dtsOutputs = generateDtsBundle([
+  {
+    filePath: "./src/index.ts",
+    output: {
+      noBanner: true,
+    },
+  },
+]);
+
+// The function returns an array of strings corresponding to each entry point.
+fs.writeFileSync("./dist/index.d.ts", dtsOutputs[0]);
+```
+
+## API Reference
+
+### `generateDtsBundle(entries, options?)`
+
+Generates bundled declaration files for the provided entry points.
+
+- `entries`: An array of EntryPointConfig objects.
+- `options` (optional): A `CompilationOptions` object.
+- Returns: `string[]` – An array of bundled `.d.ts` strings in the exact same order as the provided entries.
+
+### Configuration Interfaces
+
+#### `EntryPointConfig`
+
+Defines the configuration for a single entry point.
+
+- `filePath` (string): Path to the input file.
+- `libraries` (optional): Options for handling external dependencies (`LibrariesOptions`).
+- `failOnClass` (optional): Fail if the generated dts contains a class declaration.
+- `output` (optional): Formatting and output options (`OutputOptions`).
+
+#### `OutputOptions`
+
+Controls the behavior of the output generation.
+
+- `sortNodes`: Sort output nodes in ascendant order.
+- `umdModuleName`: Name of the UMD module. Emits `export as namespace ModuleName;` if specified.
+- `inlineDeclareGlobals`: Enables inlining of `declare global` statements from inlined files/packages.
+- `inlineDeclareExternals`: Enables inlining of `declare module` statements for global modules.
+- `noBanner`: Removes the "Generated by dts-bundle-generator" style banner/license block from the output.
+- `respectPreserveConstEnum`: Strips the `const` keyword from exported `const enum`s to avoid TS preserving issues.
+- `exportReferencedTypes`: Defaults to `true`. Disable to ensure nodes are exported only if explicitly exported from the root source file.
+
+#### `LibrariesOptions`
+
+Configures how `node_modules` and `@types` are handled.
+
+- `inlinedLibraries`: Array of package names to inline typings from.
+- `importedLibraries`: Array of package names to import typings from. By default, all non-inlined and non-@types libraries are imported.
+- `allowedTypesLibraries`: Array of `@types` packages allowed to be imported via triple-slash references.
+
+#### `CompilationOptions`
+
+Global options for the compiler host.
+
+- `followSymlinks`: (Experimental) Disable resolving symlinks to the original path (defaults to true).
+- `preferredConfigPath`: Explicit path to the `tsconfig.json` file to use.
+
+## License
+
+MIT © SSE World