echo-banner 0.1.0 → 0.3.0

package/README.md

@@ -39,19 +39,16 @@ console.log(result);
 
 ### `banner(options)`
 
-Generate a formatted banner string.
+Generate a formatted banner string. See the [API docs](https://teneplaysofficial.github.io/echo-banner/functions/banner.html)
 
 ```ts
 banner(options: BannerOptions): string
 ```
 
-#### Options
+### `print(options)`
 
-| Option           | Type                                  | Default                                 | Description                                                    |
-| ---------------- | ------------------------------------- | --------------------------------------- | -------------------------------------------------------------- |
-| `pkg`            | `PackageMeta`                         | **required**                            | Package metadata (usually imported from `package.json`).       |
-| `shebang`        | `string \| false`                     | `false`                                 | Adds a shebang line before the banner (useful for CLI builds). |
-| `style`          | `'js'`                                | `'js'`                                  | Banner comment style.                                          |
-| `useDisplayName` | `boolean`                             | `false`                                 | Use `displayName` instead of `name`.                           |
-| `prefixVersion`  | `string`                              | `'v'`                                   | Prefix added before the version.                               |
-| `fallback`       | `{ name?: string; version?: string }` | `{ name: 'unknown', version: '0.0.0' }` | Fallback values when metadata is missing.                      |
+Prints a stylized ASCII banner for CLI applications. See the [API docs](https://teneplaysofficial.github.io/echo-banner/functions/print.html)
+
+```ts
+print(options: PrintOptions): Promise<void>
+```

package/dist/index.cjs

@@ -1,5 +1,5 @@
 /*!
- * echo-banner v0.1.0
+ * echo-banner v0.3.0
  * Generate multiline build banners and ASCII CLI titles
  * 
  * (c) 2026 Sriman
@@ -8,4 +8,4 @@
  * https://teneplaysofficial.github.io/echo-banner
  * https://github.com/teneplaysofficial/echo-banner
  */
-Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});let e=require(`node:os`);function t({pkg:t,shebang:n=!1,style:r=`js`,useDisplayName:i=!1,prefixVersion:a=`v`,fallback:o={name:`unknown`,version:`0.0.0`}}){if(!t||typeof t!=`object`)throw TypeError(`Expected valid metadata`);let s=``,c=[],l=new Date().getFullYear(),u=/^(git\+)|(\.git)$/g;n&&(s+=n+e.EOL.repeat(2)),c.push(`${(i?t.displayName:t.name)??o.name} ${a}${t.version??o.version}`),c.push(t.description??``),c.push(``),c.push(`(c) ${l} ${(typeof t.author==`object`?t.author.name:t.author)??``}`),t.license&&c.push(`Released under the ${t.license} License`),c.push(``);let d=t.homepage;d&&c.push(d);let f=typeof t.repository==`object`?t.repository.url?.replace(u,``):t.repository?.replace(u,``);switch(f&&c.push(f),r){case`js`:s+=[`/*!`,...c.slice(0,c.findLastIndex(e=>e!==``)+1).map(e=>` * ${e}`),` */`].join(e.EOL);break}return s}exports.banner=t;
+Object.defineProperty(exports,Symbol.toStringTag,{value:`Module`});var e=Object.create,t=Object.defineProperty,n=Object.getOwnPropertyDescriptor,r=Object.getOwnPropertyNames,i=Object.getPrototypeOf,a=Object.prototype.hasOwnProperty,o=(e,i,o,s)=>{if(i&&typeof i==`object`||typeof i==`function`)for(var c=r(i),l=0,u=c.length,d;l<u;l++)d=c[l],!a.call(e,d)&&d!==o&&t(e,d,{get:(e=>i[e]).bind(null,d),enumerable:!(s=n(i,d))||s.enumerable});return e},s=(n,r,a)=>(a=n==null?{}:e(i(n)),o(r||!n||!n.__esModule?t(a,`default`,{value:n,enumerable:!0}):a,n));let c=require(`node:os`),l=require(`figlet`);l=s(l);let u=require(`use-colors`);u=s(u);function d({pkg:e,shebang:t=!1,style:n=`js`,useDisplayName:r=!1,prefixVersion:i=`v`,fallback:a={name:`unknown`,version:`0.0.0`}}){if(!e||typeof e!=`object`)throw TypeError(`Expected valid metadata`);let o=``,s=[],l=new Date().getFullYear(),u=/^(git\+)|(\.git)$/g;t&&(o+=t+c.EOL.repeat(2)),s.push(`${(r?e.displayName:e.name)??a.name} ${i}${e.version??a.version}`),s.push(e.description??``),s.push(``),s.push(`(c) ${l} ${(typeof e.author==`object`?e.author.name:e.author)??``}`),e.license&&s.push(`Released under the ${e.license} License`),s.push(``);let d=e.homepage;d&&s.push(d);let f=typeof e.repository==`object`?e.repository.url?.replace(u,``):e.repository?.replace(u,``);switch(f&&s.push(f),n){case`js`:o+=[`/*!`,...s.slice(0,s.findLastIndex(e=>e!==``)+1).map(e=>` * ${e}`),` */`].join(c.EOL);break}return o}async function f({pkg:e,useVersion:t=!0,useDisplayName:n=!0,prefixVersion:r=`v`,font:i=`Slant`,color:a=!0}){let o=n&&e.displayName||e.name;if(!o)return;a||u.default.config({level:0});let s=await l.default.text(o,{font:i});if(!t||!e.version){console.log(u.default.cyanBright(s));return}let d=s.split(c.EOL),f=u.default.gray`${r}${e.version}`,p=d.findLastIndex(e=>e.trim().length>0);if(p<0){console.log(u.default.cyanBright(s));return}let m=Math.max(...d.map(e=>e.trimEnd().length)),h=d[p].trimEnd(),g=m-h.length+2;d[p]=u.default.cyanBright(h)+` `.repeat(g)+f,console.log(d.join(c.EOL))}exports.banner=d,exports.print=f;

package/dist/index.d.cts

@@ -4,6 +4,51 @@ import { PackageJson, SHEBANG } from "js-utils-kit";
 //#region lib/index.d.ts
 type Shebang = (typeof SHEBANG)[keyof typeof SHEBANG];
 type PackageMeta = Pick<PackageJson, 'name' | 'displayName' | 'version' | 'description' | 'author' | 'license' | 'homepage' | 'repository'>;
+/**
+ * Generate a production banner comment from package metadata.
+ *
+ * @remarks
+ * This utility creates a formatted banner typically used at the top of bundled files (e.g., Rollup, tsdown, esbuild, webpack outputs).
+ *
+ * The banner includes:
+ * - Package name or display name
+ * - Version (with optional prefix)
+ * - Description
+ * - Copyright
+ * - License
+ * - Homepage
+ * - Repository URL
+ *
+ * Repository URLs are normalized by removing common prefixes such as `git+` and suffixes like `.git`.
+ *
+ * @returns A formatted banner string suitable for insertion at the top of bundled files.
+ *
+ * @throws {TypeError} Thrown if the provided `pkg` value is not a valid object.
+ *
+ * @example Basic usage
+ * ```ts
+ * import pkg from "../package.json";
+ *
+ * const text = banner({ pkg });
+ * console.log(text);
+ * ```
+ *
+ * @example With shebang for CLI tools
+ * ```ts
+ * const text = banner({
+ *   pkg,
+ *   shebang: "#!/usr/bin/env node"
+ * });
+ * ```
+ *
+ * @example Using display name
+ * ```ts
+ * const text = banner({
+ *   pkg,
+ *   useDisplayName: true
+ * });
+ * ```
+ */
 declare function banner({
   pkg,
   shebang,
@@ -12,15 +57,133 @@ declare function banner({
   prefixVersion,
   fallback
 }: {
-  pkg: PackageMeta;
+  /** Package metadata used to construct the banner */pkg: PackageMeta;
+  /**
+   * Optional shebang line (for CLI binaries).
+   *
+   * @default false
+   */
   shebang?: Shebang | false;
-  style?: 'js';
+  /**
+   * Banner comment style.
+   *
+   * Currently supports:
+   * - `js`
+   *
+   * @default "js"
+   */
+  style?: 'js'; /** Prefer `displayName` over `name` when available */
   useDisplayName?: boolean;
-  prefixVersion?: string;
+  /**
+   * Prefix applied before the version.
+   *
+   * @default "v"
+   */
+  prefixVersion?: string; /** Fallback values when `name` or `version` are missing */
   fallback?: {
     name?: string;
     version?: string;
   };
 }): string;
+type FontName = '1Row' | '3-D' | '3D Diagonal' | '3D-ASCII' | '3x5' | '4Max' | '5 Line Oblique' | 'Standard' | 'Ghost' | 'Big' | 'Block' | 'Bubble' | 'Digital' | 'Ivrit' | 'Mini' | 'Script' | 'Shadow' | 'Slant' | 'Small' | 'Speed' | 'Tinker-Toy';
+/**
+ * Prints a stylized banner of a package name using a FIGlet font.
+ *
+ * The banner can optionally include the package version appended to the last visible line of the generated ASCII text.
+ *
+ * This is useful for CLI tools to display a startup banner with project name and version.
+ *
+ * @remarks
+ * - If `displayName` is available and `useDisplayName` is `true`, it will be used instead of `name`.
+ * - If `useVersion` is enabled and `pkg.version` exists, the version will be aligned to the
+ *   right side of the banner's last visible line.
+ * - If the banner contains no printable lines, the raw FIGlet output is printed.
+ * - If `color` is disabled, all ANSI styling is turned off.
+ *
+ * @example
+ * ```ts
+ * import { print } from "echo-banner";
+ * import pkg from "../package.json";
+ *
+ * await print({
+ *   pkg,
+ *   font: "Slant"
+ * });
+ * ```
+ *
+ * @example Custom version prefix
+ * ```ts
+ * await print({
+ *   pkg,
+ *   prefixVersion: "@",
+ * });
+ * ```
+ *
+ * @example Disable version output
+ * ```ts
+ * await print({
+ *   pkg,
+ *   useVersion: false
+ * });
+ * ```
+ *
+ * @example Use package name instead of display name
+ * ```ts
+ * await print({
+ *   pkg,
+ *   useDisplayName: false
+ * });
+ * ```
+ *
+ * @example Disable colors
+ * ```ts
+ * await print({
+ *   pkg,
+ *   color: false
+ * });
+ * ```
+ */
+declare function print({
+  pkg,
+  useVersion,
+  useDisplayName,
+  prefixVersion,
+  font,
+  color
+}: {
+  /** Package metadata containing the name, optional display name, and version. */pkg: Pick<PackageMeta, 'name' | 'displayName' | 'version'>;
+  /**
+   * Whether to append the version to the banner.
+   *
+   * @default true
+   */
+  useVersion?: boolean;
+  /**
+   * Prefer `displayName` over `name` when available.
+   *
+   * @default true
+   */
+  useDisplayName?: boolean;
+  /**
+   * Prefix added before the version string.
+   *
+   * @default "v"
+   *
+   * @example "v1.0.0"
+   */
+  prefixVersion?: string;
+  /**
+   * Figlet font used to render the banner.
+   *
+   * @default "Slant"
+   */
+  font?: FontName;
+  /**
+   * Enable or disable colored output.
+   *
+   * @default true
+   */
+  color?: boolean;
+}): Promise<void>;
 //#endregion
-export { banner };
+export { banner, print };

package/dist/index.d.mts

@@ -4,6 +4,51 @@ import { PackageJson, SHEBANG } from "js-utils-kit";
 //#region lib/index.d.ts
 type Shebang = (typeof SHEBANG)[keyof typeof SHEBANG];
 type PackageMeta = Pick<PackageJson, 'name' | 'displayName' | 'version' | 'description' | 'author' | 'license' | 'homepage' | 'repository'>;
+/**
+ * Generate a production banner comment from package metadata.
+ *
+ * @remarks
+ * This utility creates a formatted banner typically used at the top of bundled files (e.g., Rollup, tsdown, esbuild, webpack outputs).
+ *
+ * The banner includes:
+ * - Package name or display name
+ * - Version (with optional prefix)
+ * - Description
+ * - Copyright
+ * - License
+ * - Homepage
+ * - Repository URL
+ *
+ * Repository URLs are normalized by removing common prefixes such as `git+` and suffixes like `.git`.
+ *
+ * @returns A formatted banner string suitable for insertion at the top of bundled files.
+ *
+ * @throws {TypeError} Thrown if the provided `pkg` value is not a valid object.
+ *
+ * @example Basic usage
+ * ```ts
+ * import pkg from "../package.json";
+ *
+ * const text = banner({ pkg });
+ * console.log(text);
+ * ```
+ *
+ * @example With shebang for CLI tools
+ * ```ts
+ * const text = banner({
+ *   pkg,
+ *   shebang: "#!/usr/bin/env node"
+ * });
+ * ```
+ *
+ * @example Using display name
+ * ```ts
+ * const text = banner({
+ *   pkg,
+ *   useDisplayName: true
+ * });
+ * ```
+ */
 declare function banner({
   pkg,
   shebang,
@@ -12,15 +57,133 @@ declare function banner({
   prefixVersion,
   fallback
 }: {
-  pkg: PackageMeta;
+  /** Package metadata used to construct the banner */pkg: PackageMeta;
+  /**
+   * Optional shebang line (for CLI binaries).
+   *
+   * @default false
+   */
   shebang?: Shebang | false;
-  style?: 'js';
+  /**
+   * Banner comment style.
+   *
+   * Currently supports:
+   * - `js`
+   *
+   * @default "js"
+   */
+  style?: 'js'; /** Prefer `displayName` over `name` when available */
   useDisplayName?: boolean;
-  prefixVersion?: string;
+  /**
+   * Prefix applied before the version.
+   *
+   * @default "v"
+   */
+  prefixVersion?: string; /** Fallback values when `name` or `version` are missing */
   fallback?: {
     name?: string;
     version?: string;
   };
 }): string;
+type FontName = '1Row' | '3-D' | '3D Diagonal' | '3D-ASCII' | '3x5' | '4Max' | '5 Line Oblique' | 'Standard' | 'Ghost' | 'Big' | 'Block' | 'Bubble' | 'Digital' | 'Ivrit' | 'Mini' | 'Script' | 'Shadow' | 'Slant' | 'Small' | 'Speed' | 'Tinker-Toy';
+/**
+ * Prints a stylized banner of a package name using a FIGlet font.
+ *
+ * The banner can optionally include the package version appended to the last visible line of the generated ASCII text.
+ *
+ * This is useful for CLI tools to display a startup banner with project name and version.
+ *
+ * @remarks
+ * - If `displayName` is available and `useDisplayName` is `true`, it will be used instead of `name`.
+ * - If `useVersion` is enabled and `pkg.version` exists, the version will be aligned to the
+ *   right side of the banner's last visible line.
+ * - If the banner contains no printable lines, the raw FIGlet output is printed.
+ * - If `color` is disabled, all ANSI styling is turned off.
+ *
+ * @example
+ * ```ts
+ * import { print } from "echo-banner";
+ * import pkg from "../package.json";
+ *
+ * await print({
+ *   pkg,
+ *   font: "Slant"
+ * });
+ * ```
+ *
+ * @example Custom version prefix
+ * ```ts
+ * await print({
+ *   pkg,
+ *   prefixVersion: "@",
+ * });
+ * ```
+ *
+ * @example Disable version output
+ * ```ts
+ * await print({
+ *   pkg,
+ *   useVersion: false
+ * });
+ * ```
+ *
+ * @example Use package name instead of display name
+ * ```ts
+ * await print({
+ *   pkg,
+ *   useDisplayName: false
+ * });
+ * ```
+ *
+ * @example Disable colors
+ * ```ts
+ * await print({
+ *   pkg,
+ *   color: false
+ * });
+ * ```
+ */
+declare function print({
+  pkg,
+  useVersion,
+  useDisplayName,
+  prefixVersion,
+  font,
+  color
+}: {
+  /** Package metadata containing the name, optional display name, and version. */pkg: Pick<PackageMeta, 'name' | 'displayName' | 'version'>;
+  /**
+   * Whether to append the version to the banner.
+   *
+   * @default true
+   */
+  useVersion?: boolean;
+  /**
+   * Prefer `displayName` over `name` when available.
+   *
+   * @default true
+   */
+  useDisplayName?: boolean;
+  /**
+   * Prefix added before the version string.
+   *
+   * @default "v"
+   *
+   * @example "v1.0.0"
+   */
+  prefixVersion?: string;
+  /**
+   * Figlet font used to render the banner.
+   *
+   * @default "Slant"
+   */
+  font?: FontName;
+  /**
+   * Enable or disable colored output.
+   *
+   * @default true
+   */
+  color?: boolean;
+}): Promise<void>;
 //#endregion
-export { banner };
+export { banner, print };

package/dist/index.mjs

@@ -1,5 +1,5 @@
 /*!
- * echo-banner v0.1.0
+ * echo-banner v0.3.0
  * Generate multiline build banners and ASCII CLI titles
  * 
  * (c) 2026 Sriman
@@ -8,4 +8,4 @@
  * https://teneplaysofficial.github.io/echo-banner
  * https://github.com/teneplaysofficial/echo-banner
  */
-import{EOL as e}from"node:os";function t({pkg:t,shebang:n=!1,style:r=`js`,useDisplayName:i=!1,prefixVersion:a=`v`,fallback:o={name:`unknown`,version:`0.0.0`}}){if(!t||typeof t!=`object`)throw TypeError(`Expected valid metadata`);let s=``,c=[],l=new Date().getFullYear(),u=/^(git\+)|(\.git)$/g;n&&(s+=n+e.repeat(2)),c.push(`${(i?t.displayName:t.name)??o.name} ${a}${t.version??o.version}`),c.push(t.description??``),c.push(``),c.push(`(c) ${l} ${(typeof t.author==`object`?t.author.name:t.author)??``}`),t.license&&c.push(`Released under the ${t.license} License`),c.push(``);let d=t.homepage;d&&c.push(d);let f=typeof t.repository==`object`?t.repository.url?.replace(u,``):t.repository?.replace(u,``);switch(f&&c.push(f),r){case`js`:s+=[`/*!`,...c.slice(0,c.findLastIndex(e=>e!==``)+1).map(e=>` * ${e}`),` */`].join(e);break}return s}export{t as banner};
+import{EOL as e}from"node:os";import t from"figlet";import n from"use-colors";function r({pkg:t,shebang:n=!1,style:r=`js`,useDisplayName:i=!1,prefixVersion:a=`v`,fallback:o={name:`unknown`,version:`0.0.0`}}){if(!t||typeof t!=`object`)throw TypeError(`Expected valid metadata`);let s=``,c=[],l=new Date().getFullYear(),u=/^(git\+)|(\.git)$/g;n&&(s+=n+e.repeat(2)),c.push(`${(i?t.displayName:t.name)??o.name} ${a}${t.version??o.version}`),c.push(t.description??``),c.push(``),c.push(`(c) ${l} ${(typeof t.author==`object`?t.author.name:t.author)??``}`),t.license&&c.push(`Released under the ${t.license} License`),c.push(``);let d=t.homepage;d&&c.push(d);let f=typeof t.repository==`object`?t.repository.url?.replace(u,``):t.repository?.replace(u,``);switch(f&&c.push(f),r){case`js`:s+=[`/*!`,...c.slice(0,c.findLastIndex(e=>e!==``)+1).map(e=>` * ${e}`),` */`].join(e);break}return s}async function i({pkg:r,useVersion:i=!0,useDisplayName:a=!0,prefixVersion:o=`v`,font:s=`Slant`,color:c=!0}){let l=a&&r.displayName||r.name;if(!l)return;c||n.config({level:0});let u=await t.text(l,{font:s});if(!i||!r.version){console.log(n.cyanBright(u));return}let d=u.split(e),f=n.gray`${o}${r.version}`,p=d.findLastIndex(e=>e.trim().length>0);if(p<0){console.log(n.cyanBright(u));return}let m=Math.max(...d.map(e=>e.trimEnd().length)),h=d[p].trimEnd(),g=m-h.length+2;d[p]=n.cyanBright(h)+` `.repeat(g)+f,console.log(d.join(e))}export{r as banner,i as print};

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "echo-banner",
   "displayName": "Echo Banner",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Generate multiline build banners and ASCII CLI titles",
   "keywords": [
     "cli",
@@ -41,6 +41,7 @@
   },
   "scripts": {
     "build": "tsdown",
+    "build:docs": "typedoc",
     "fmt": "prettier --write .",
     "fmt:check": "prettier --check .",
     "lint": "biome check",
@@ -52,7 +53,8 @@
   },
   "dependencies": {
     "figlet": "^1.10.0",
-    "js-utils-kit": "^2.1.0"
+    "js-utils-kit": "^2.1.0",
+    "use-colors": "^0.1.0"
   },
   "devDependencies": {
     "@biomejs/biome": "^2.4.5",
@@ -63,6 +65,7 @@
     "lint-staged": "^16.3.2",
     "prettier": "^3.8.1",
     "tsdown": "^0.20.3",
+    "typedoc": "^0.28.17",
     "typescript": "^5.9.3",
     "vitest": "^4.0.18"
   },