Browser String Format Utility

Common errors

• SyntaxError: Named export 'format' not found. The requested module 'format-util' does not provide an export named 'format'

  cause Attempting to use ES module named import syntax (`import { format } from 'format-util';`) on a CommonJS-only package.
  fix Change the import statement to `const format = require('format-util');` for CommonJS compatibility.

• TypeError: format is not a function

  cause Occurs when a bundler's CJS-ESM interop is misconfigured, or when attempting to use a default ESM import (`import format from 'format-util';`) where the CJS module exports a single function via `module.exports = fn;` and the interop doesn't correctly resolve it.
  fix Ensure your bundler correctly handles CommonJS modules. In a Node.js CJS environment, stick to `const format = require('format-util');`.

• Cannot find name 'format'.

  cause This error appears in TypeScript projects because the `format-util` package lacks official type definitions.
  fix Add a custom declaration file (e.g., `format-util.d.ts`) containing `declare module 'format-util' { function format(...args: any[]): string; export = format; }` to your project's `src/types` directory or similar.

Warnings

• breaking The `format-util` package is abandoned and no longer actively maintained. This means there will be no new features, bug fixes, or security updates. Relying on it in new projects is strongly discouraged.
  Fix: Migrate to actively maintained alternatives such as native template literals, or if in Node.js, `util.format` directly. For browser environments requiring similar functionality, consider libraries like `sprintf-js` or roll your own simple formatting utility.
• gotcha This package is CommonJS-only. Using it directly with ES module `import` syntax will cause runtime errors in native ESM environments (e.g., Node.js with `type: module` or modern browsers) unless a bundler provides CJS-ESM interop.
  Fix: Use `const format = require('format-util');` in CJS environments. In ESM, either configure your bundler (like Webpack or Rollup) for CJS interop, or use dynamic import `import('format-util').then(module => module.exports);` (though this might not work as expected for simple exports).
• gotcha There are no official TypeScript type definitions (`.d.ts` files) available for `format-util`. TypeScript projects will not recognize the `format` function without custom declarations.
  Fix: Create a declaration file (e.g., `src/types/format-util.d.ts`) with `declare module 'format-util' { function format(...args: any[]): string; export = format; }` or use `// @ts-ignore` to suppress type errors.
• gotcha The functionality of `format-util` is a simplified port of Node.js's `util.format`. It may not include all advanced specifiers or behaviors found in the latest Node.js versions of `util.format` (e.g., `%o`, `%O`, custom formatters).
  Fix: Consult the `format-util` source or Node.js `util.format` documentation for specific behavior. For full Node.js `util.format` compatibility in non-Node environments, consider more comprehensive polyfills or reimplementations.

Install

• npm install format-util npm
• yarn add format-util yarn
• pnpm add format-util pnpm

Imports

• format
  wrong:

  import { format } from 'format-util';

  correct:

  const format = require('format-util');

  This package is CommonJS-only (CJS) and does not provide native ES module (ESM) exports. Direct `import` statements will fail without a bundler's CJS interop layer.
• format (for browser)
  wrong:

  import format from 'format-util';

  correct:

  var format = require('format-util');

  Designed for older browser environments with CJS bundling (e.g., Browserify). Modern browser applications would typically use native template literals or a more actively maintained library for string formatting, or rely on a bundler to transpile this CJS module.
• Type definitions
  wrong:

  import type { FormatFunction } from 'format-util';

  correct:

  // No built-in types; define manually if using TypeScript.

  The package does not ship with TypeScript declarations. Users must create a `d.ts` file or use `// @ts-ignore` for TypeScript compatibility.

Quickstart

Demonstrates basic string formatting with different specifiers (%s, %d, %j) and argument handling.

const format = require('format-util');

// Basic string formatting: %s for strings
let message1 = format('Hello, %s!', 'World');
console.log(message1);
// Expected: "Hello, World!"

// Formatting with multiple arguments: %d for numbers
let message2 = format('User %d logged in from %s.', 123, '192.168.1.100');
console.log(message2);
// Expected: "User 123 logged in from 192.168.1.100."

// Handling objects: %j for JSON representation
let userInfo = { id: 456, name: 'Alice' };
let message3 = format('User data: %j', userInfo);
console.log(message3);
// Expected: "User data: {\"id\":456,\"name\":\"Alice\"}"

// Combining different types and handling extra arguments
let message4 = format('Item: %s, Quantity: %d, Price: $%d. Remaining args: %s', 'Laptop', 2, 1200, 'extra data');
console.log(message4);
// Expected: "Item: Laptop, Quantity: 2, Price: $1200. Remaining args: extra data"

// Example demonstrating a common type mismatch (util.format converts non-numbers to NaN for %d)
let message5 = format('The number is %d.', 'forty-two');
console.log(message5);
// Expected: "The number is NaN."

// This utility is often used for building log messages or dynamic display strings.