@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

Parameter	Type	Description
init	object	An object with configuration options to initalise the Banner instance.
init.data?	object	An object containing data to be merged in to the banner comment template. Object keys should match the placeholdes in the template, and values can be either a string, number or a function expression that receives the previous value as a string and returns a new value.
init.templates	object	An object containing templates for generating banner comments. Each key should be a glob string used to match the template to a file, and each value should be a template specified as an array of strings.

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

Parameter	Type	Description
pattern	string	A valid glob pattern to find all files relative to the current working directory to apply banner comments to.
options?	object	An object for specifying options for how banner comments will be applied to matching files.
options.chunkSize?	number	Sets the amount of data in bytes to process per chunk. This should not be set lower than the potential size of a banner comment i.e. the comment needs to fit in a sigle chunk, otherwise existing comments may not be matched and updated. Default Value 16384 (16 KiB)
options.remove?	boolean	Specifies if banner comments should be removed. Default Value false
options.write?	boolean	Specifies whether to write back to the files. Default Value false

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

Parameter	Type	Description
template	string	The banner comment template specified as a string. The template can include placeholders using {{ key }} syntax for values specified in an object passed to the options.data parameter.
options?	object	An object for specifying options for how a banner comment will be applied to the stream content.
options.chunkSize?	number	Sets the amount of data in bytes the transform stream will process per chunk. This should not be set lower than the potential size of a banner comment i.e. the comment needs to fit in a sigle chunk, otherwise the stream will fail to replace an existing comment. Default Value 16384 (16 KiB)
options.data?	object	Optionally provide an object with values to replace placeholders in the banner comment template. Object keys should match the placeholdes in the template, and values can be either a string, number or a function expression that receives the previous value as a string and returns a new value.
options.remove?	boolean	Specifies if the banner comment should be removed. Default Value false

Overrides

Transform.constructor

Source

transform.ts:64

Methods

apply()

apply(content): string

Applies the banner comment to the content of a file.

Parameters

Parameter	Type	Description
content	string	The content of the file provided as a single string.

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

Parameter	Type	Description
content	AsyncIterable<string | Buffer>	The content of the file provided as an async iterable that yields chunks of the file.

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.