bingo-fs

The virtual file system used by Bingo. 🗄️

npm

npm i bingo-fs

pnpm

pnpm add bingo-fs

yarn

yarn add bingo-fs

The separate bingo-fs package includes types and utility functions for the file system used in Concepts > Creations > files.

This file system is a simplified abstraction over the lower-level APIs in Node.js and other platforms. APIs and data are optimized for simplicity and ease of use, rather than completeness.

For example, given a structure like:

/
└── README.md
└── src
    └── index.ts

bingo-fs would represent that structure with an object like:

{
  "README.md": "...",
  "src": {
    "index.ts": "..."
  }
}

Directories

TypeScript type name: CreatedDirectory

Directories in a files object are represented as objects. Property keys are the names of children. Values are the file or directory underneath that key.

IntakeDirectory

Directories read in from intake or intakeDirectory are represented as IntakeDirectory objects. IntakeDirectory objects represent files as [string, CreatedFileMetadata?] tuples.

Note

Windows file modes don’t include executable bits, so Node.js can’t tell whether a file is executable. On Windows, files are read in without executable metadata: ["..."] instead of ["...", { executable: false }].

Files

TypeScript type name: CreatedFileEntry

Each property value in a directory object may be one of the following:

• false or undefined: Ignored
• object: A directory, whose properties recursively are file creations
• string: A file to be created
• [string, CreatedFileMetadata?]: A file to be created with options:
  • executable: Whether to add permissions to make the file executable
  • previously: Paths, relative to the file’s directory, that earlier versions of the file were created at

For example, this Bingo template produces an executable .husky/pre-commit file:

import { createTemplate } from "bingo";

export default createTemplate({
  produce() {
    return {
      ".husky": {
        "pre-commit": ["npx lint-staged\n", { executable: true }],
      },
    };
  },
});

Files with previously paths are treated as the same file by Stratum’s Preset Inference, and any files at those paths are removed after the file is written. For example, this Bingo template produces a .github/FUNDING.yaml file that used to be .github/FUNDING.yml:

import { createTemplate } from "bingo";

export default createTemplate({
  produce() {
    return {
      ".github": {
        "FUNDING.yaml": ["github: abc", { previously: ["FUNDING.yml"] }],
      },
    };
  },
});

APIs

intake

Given a directory or file path, reads it in as a bingo-fs directory structure or file entry.

Parameters:

1. rootPath: string (required)
2. settings: IntakeSettings (optional):
   • exclude: RegExp

Returns the directory or file if it existed, or undefined if it didn’t.

For example, retrieving all files in a src/ directory:

import { intake } from "bingo-fs";

// { "index.ts": "..." }
await intake("src");

exclude

An optional regular expression to filter out directory children.

For example, you may want to avoid .git and node_modules directories:

import { intake } from "bingo-fs";

// Result: { README.md: "...", src: { "index.ts": "..." }, ... }
await intake(".", {
  exclude: /node_modules|^\.git$/,
});

intakeDirectory

Given a directory path, reads it in as a bingo-fs directory structure.

Parameters:

1. directoryPath: string (required)
2. settings: IntakeSettings (optional):
   • exclude: RegExp

Returns the directory or file if it existed, or undefined if it didn’t.

For example, retrieving all files in a src/ directory:

import { intakeDirectory } from "bingo-fs";

// { "index.ts": "..." }
await intakeDirectory("src");

exclude

An optional regular expression to filter out directory children.

For example, you may want to avoid .git and node_modules directories:

import { intakeDirectory } from "bingo-fs";

// Result: { README.md: "...", src: { "index.ts": "..." }, ... }
await intakeDirectory(".", {
  exclude: /node_modules|^\.git$/,
});