@marktuk/banner v1.1.0

@marktuk/banner

A simple tool that will apply a custom banner comment to multiple files in a project.

There are a few existing tools that can be used to write a banner comment to files in a project. However, many of them are not actively maintained, and no single tool had the all of features I wanted. This tool provides the following features:

• Apply banner comments to files matching a specified glob pattern
• Configure multiple banner comment templates for different glob patterns
• Use placeholders in banner templates to merge in values from a package.json

Table of Contents

• Install
• Usage
  • Configuration
  • CLI
  • API
• Contributing
• Licence

Install

$ npm install --save-dev @marktuk/banner

Usage

Configuration

The templates can be configured by adding a banner object to your package.json.

The configuration should be an object where each value is a template as an array of strings and it's key is a glob pattern to use to apply the template to matching files.

The templates support basic mustache style tags for merging in values from the package.json. The following package.json values are supported:

• name
• version
• description
• author
• licence

The following additional values are also supported:

• file - path and filename of the current file relative to the current working directory.
• year - the current year.
• yearRange - the existing year and the current year as a range e.g. "2021-2024". Defaults to the current year if there is no existing year.

Example configuration:

{
    "banner": {
        "{src,test}/**/**.{ts,js}": [
            "/*!",
            " * {{ name }} v{{ version }}",
            " * {{ file }}",
            " * Copyright (c) {{ year }} {{ author }}",
            " * Released under the terms of the {{ license }} license",
            " */"
        ],
        "{src,test}/**/**.{yml,yaml}": [
            "# {{ name }} v{{ version }}",
            "# {{ file }}",
            "# Copyright (c) {{ year }} {{ author }}",
            "# Released under the terms of the {{ license }} license"
        ]
    }
}

CLI

The banner CLI is the easiest way to apply banner comments to files.

Usage: banner [options] [file/dir/glob...]

Generate a banner comment for file(s) and append it to the start of the file.

Options:
  -h, --help      Show CLI usage.
  -r, --remove    Remove existing banner comment from given file(s).
  -v, --verbose   Output additional information when writing to files.
  -w, --write     Edit files in-place. (Beware!)

API

You can also apply banner comments programmatically in typescript or javascript.

import { Banner } from '@marktuk/banner';

Banner.fromPackageJson().then((banner) =>
    banner.apply('{src,test}/**/**.{ts,js,yml,yaml}', { write: true })
);

Banner

Instances of the Banner class are used to add, update or remove a banner comments from the content of multiple files.

Constructors

new Banner(init)

new Banner(init): Banner

Creates an instance of the Banner class.

Parameters

Source

banner.ts:72

Methods

apply()

apply(pattern, options?): AsyncGenerator<[string, string], void, void>

Adds, updates or removes banner comments for all files that match a specified glob string pattern and optionally writes back to the files.

Parameters

Returns

An asynchronous generator that yields a tuple containing a processed file path and chunk.

Source

banner.ts:128

fromPackageJson()

static fromPackageJson(): Promise<Banner>

Creates an instance of the Banner class configured using the nearest package.json.

Source

banner.ts:33

BannerTransform

Instances of the BannerTransform class are used to add, update or remove a banner comment from the content of a file. The class can be used in the following ways:

• As a transform stream, to process a readable stream and write the result to another stream.
• Using the asyncIterator() method to process an async iterable and return an async iterable with the result.
• Using the apply() method to process a single string and return the result.

Extends

• Transform

Constructors

new BannerTransform(template, options)

new BannerTransform(template, options?): BannerTransform

Creates an instance of the BannerTransform class.

Parameters

Overrides

Transform.constructor

Source

transform.ts:64

Methods

apply()

apply(content): string

Applies the banner comment to the content of a file.

Parameters

Returns

The content of the file with the banner comment added, updated or removed.

Source

transform.ts:159

asyncIterator()

asyncIterator(content): AsyncGenerator<string, void, unknown>

Asynchronously apply a banner comment to the content of a file, processing the file in chunks. The banner comment will only be added, updated or removed from the first chunk.

Parameters

Returns

An asynchronous generator that yields the content of the file with the banner comment added, updated or removed.

Source

transform.ts:140

Contributing

I created this tool mainly to use in my own projects, so I am not planning to actively develop it or add new features. If you want a new feature I would recommend creating a new issue to discuss it before you create a pull request.

I do plan to maintain the tool so if you find a bug please do create an issue. Pull requests to fix bugs are also welcome.

You are also free to fork this project and use the source code as you wish under the terms of the MIT No Attribution licence.

Licence

Copyright © 2023 Mark Tyrrell, all rights reserved.
Released under the terms of the MIT license.