Ensure: ensureFinalNewline - Build Tools

Overview

ensureFinalNewline ensures matched files end with exactly one final newline character.

It removes trailing newline characters at the end of each file, then appends a single platform-consistent newline while preserving all internal formatting and whitespace.

Why use this?

Ensures exactly one final newline at the end of each file.
Supports both LF (\n) and CRLF (\r\n).
Fully idempotent.
Preserves internal formatting and whitespace.
Writes only when file content changes.
Useful for post-build output normalization and POSIX compatibility.

Importing

import { ensureFinalNewline } from "@rzl-zone/build-tools";

const { ensureFinalNewline } = require("@rzl-zone/build-tools");

Syntax

ensureFinalNewline(
  pattern: StringCollection,
  options?: EnsureFinalNewlineOptions
): Promise<void>

ensureFinalNewline(pattern, options): Promise<void>

Parameters

Prop

Type

`pattern`

Glob pattern or list of patterns that target JavaScript output files.

Accepted values:

string ➔ single glob pattern.
string[] ➔ multiple glob patterns.
Set<string> ➔ unique collection of patterns.

Supported glob features

Patterns support common glob syntax, including:

* ➔ match any characters except /.
** ➔ match nested directories.
{} ➔ brace expansion (match multiple extensions or patterns).
! ➔ exclude patterns (can be combined with options.patternOptions.ignore).

Info

Pattern resolution behavior can be customized via options.patternOptions (e.g. hidden files, case sensitivity, concurrency, and ignore rules).

Examples

TypeScript/JavaScript

// Single pattern
ensureFinalNewline("dist/**/*.js");

// Multiple patterns
ensureFinalNewline(["dist/**/*.js", "build/**/*.js"]);

// Using Set
ensureFinalNewline(new Set(["dist/**/*.js"]));

// With options
ensureFinalNewline("dist/**/*.{js,cjs,mjs}", {
  patternOptions: {
    ignore: ["**/*.test.js"]
  }
});

// Exclude pattern
ensureFinalNewline([
  "dist/**/*.{js,cjs,mjs}",
  "!dist/**/*.test.js"
]);

`options`

Optional configuration object that defines how the utility function should behave in various scenarios, allowing customization and greater control at runtime.

`logLevel`

Description:
Controls how detailed the logger output should be during execution.
Supported values
- silent ➔ no output.
- error ➔ errors only.
- info ➔ standard logs (default).
- debug ➔ verbose logs.
Notes
- Invalid values are automatically reset to default.
- All levels include error output except silent.
Required:
Type:
"error" | "silent" | "info" | "debug"
Default:
"info"

Example:

TypeScript/JavaScript

// Minimal output (errors only)
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  logLevel: "error"
});

// Debug mode (verbose logs)
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  logLevel: "debug"
});

// Silent mode (no logs)
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  logLevel: "silent"
});

`patternOptions`

Description:
Controls how input file patterns are matched.

Used to filter or adjust which files are included during processing.
Useful for ignoring files, handling hidden files, or tweaking matching behavior.
Behavior
- Affects which files are selected.
- Can exclude unwanted files (e.g. test files).
- Falls back to default configuration when invalid type or not provided.
Required:
Type:
object

Default:

{
  absolute: false,
  baseNameMatch: false,
  caseSensitiveMatch: true,
  concurrency: os.cpus().length,
  dot: true,
  followSymbolicLinks: true,
  globstar: true,
  ignore: [],
  markDirectories: false,
  objectMode: false,
  onlyDirectories: false,
  onlyFiles: true,
  unique: true,
  throwErrorOnBrokenSymbolicLink: false
}

Example:

TypeScript/JavaScript

// Ignore source maps
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  patternOptions: {
    ignore: ["**/*.map"]
  }
});

// Case-insensitive matching
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  patternOptions: {
    caseSensitiveMatch: false
  }
});

// Disallowing patterns to match entries that begin with a period (.).
await cleanTypesBuildArtifacts("dist/**/*.{d.ts,d.cts,d.mts}", {
  patternOptions: {
    dot: false
  }
});

Returns

Returns a Promise<void>.
The function performs asynchronous file processing and does not return any value.

Version information

Since: v0.0.7.
Category: ensure.
Stability: ✅ Stable (Production-ready).

Made with ❤️ by @rzl-app