Populate-files NPM

populate-files

Populate static files with dynamic content, and make sure they stay in sync.

Introduction

populate-files is a small library to help populate a static file (like a .json) with dynamic calculated content. Perhaps loaded from an external source, or based off local changes.

It is a light wrapper around the fs module, which can ensure that the current state is not being overwritten.

Installation

npm i populate-files

Populate-files is an ESM module. That means it must be imported. To load from a CJS module, use dynamic import const { populateFiles } = await import('populate-files');.

Usage

Provide the file path and the file content, and the file will be updated.

Optionally specify that the file must be in sync, useful for enforcing files are in sync in a CI environment.

import { populateFile } from 'populate-files';

// Successfully writes json file!
await populateFile(
    {
        filePath: './foo.json',
        content: { bar: 123 },
    }
);

// Error! File has changed!
await populateFile(
    {
        filePath: './foo.json',
        content: { baz: 456 },
    },
    {
        check: true,
    }
);

API

populateFile(params, options)

Writes the provided content at file path.

params

A required object provided as first parameter.

property	type	description
filePath	`string`	Path to file to write (and check for existing content)
content	`string \\| object \\| Uint8Array \\| Promise`	Data to be written to file. Strings and Uint8Array (like Buffers) will be written literally. An object will be `JSON.stringify`ed, and pretty-formatted accordiing to user configs. A Promise may be provided instead that resolves to one of these types.

options

An optional object as the secondary parameter.

property	type	default	description
check	`boolean`	`true` if in a CI environment. Else `false`	If `true`, will fail if writing the file would result in changing the files content. Useful for CI environments to make sure the version-controlled code is up to date before deployment.
dryRun	`boolean`	`false`	If `true`, will not write file regardless of changes. Can still fail if `check` is `true`.
cwd	`string \\| URL`	`process.env.PWD`	Used as the current working directory if `params.filePath` is a relative file.