SBG Utility

2.0.11 · active · verified Sun Apr 19

SBG Utility is a collection of helper functions and modules primarily designed to support the `static-blog-generator` ecosystem. It provides functionalities such as file management (reading, writing, checking file stats), date mapping, and logging utilities. The current stable version is `2.0.11`. As a sub-package within a larger monorepo, its release cadence is tied to the main project, though specific updates for `sbg-utility` are less frequent. Key differentiators include its tight integration with the `static-blog-generator`'s internal workings and its CommonJS base with TypeScript type definitions, making it usable in both legacy and modern Node.js environments.

Common errors

```
TypeError: (0, _sbg_utility.someFunction) is not a function
```
cause Attempting to use a named export as a default import or incorrect destructuring in a CommonJS context.

fix Ensure you are using correct named imports for ESM (`import { someFunction } from 'sbg-utility';`) or proper destructuring for CommonJS (`const { someFunction } = require('sbg-utility');`). This package does not have a default export.
```
ERR_REQUIRE_ESM: Must use import to load ES Module: ...
```
cause This error is unlikely for `sbg-utility` itself (as it's CJS), but if you're trying to `require()` an ES module that *depends* on `sbg-utility` in a mixed environment, or incorrectly configure your build, it might surface.

fix Ensure that the module causing the error is loaded via `import` if it's an ES module. For `sbg-utility`, stick to `import` in TypeScript/ESM contexts or `require` in CJS contexts, respecting its underlying module type.

Warnings

gotcha While the package provides TypeScript types and supports ESM `import` syntax, it is fundamentally a CommonJS module. In environments where strict ESM loading is enforced (e.g., Node.js with `type: module` and no bundler), you might encounter issues. Prefer standard `require()` in pure CJS contexts or ensure your build system handles CJS interop for ESM imports.
Fix: For CommonJS environments, explicitly use `const { func } = require('sbg-utility');`. For modern TypeScript/ESM projects, ensure your `tsconfig.json` and build tools (like Webpack, Rollup, esbuild) are configured to correctly handle CommonJS dependencies.
gotcha This `sbg-utility` package is part of a larger `static-blog-generator` monorepo. While usable standalone, its API and design choices are often influenced by its parent project's needs. Expect some functionalities to be tailored specifically for the static blog generator workflow.
Fix: Review the GitHub repository and source code for the `static-blog-generator` project to understand the full context and intended usage of these utilities, especially for advanced or less documented features.

Install

npm install sbg-utility npm
yarn add sbg-utility yarn
pnpm add sbg-utility pnpm

Imports

debug
wrong:
```
const debug = require('sbg-utility').log.debug;
```
correct:
```
import { debug } from 'sbg-utility';
```
Many utility functions like logging are re-exported directly from the root module for convenience, despite their internal file structure. The package is fundamentally CommonJS but provides TypeScript types, allowing for modern ESM import syntax.
read, write
wrong:
```
const { read, write } = require('sbg-utility').filemanager;
```
correct:
```
import { read, write } from 'sbg-utility';
```
File management functions `read` and `write` are directly available as named exports from the top-level package, simplifying their usage compared to accessing them via nested module properties.
ReadOptions (Type)
wrong:
```
import { ReadOptions } from 'sbg-utility';
```
correct:
```
import type { ReadOptions } from 'sbg-utility';
```
The package ships with TypeScript definitions. Always use `import type` for importing types to ensure they are stripped from the JavaScript output, preventing potential runtime errors or unnecessary bundle size.

Quickstart

Demonstrates reading from and writing to files using `sbg-utility`'s file manager functions, along with logging capabilities.

import { read, write, debug } from 'sbg-utility';
import { join } from 'path';
import { existsSync, mkdirSync } from 'fs';

const outputDir = join(__dirname, 'temp_output');
if (!existsSync(outputDir)) {
  mkdirSync(outputDir, { recursive: true });
}

const filePath = join(__dirname, 'example.txt');
const outputPath = join(outputDir, 'output.txt');

async function runUtilityExample() {
  debug('Starting SBG Utility example...');
  try {
    // Create a dummy file for reading
    await write(filePath, 'Hello from sbg-utility!', 'utf8');
    debug(`Written to ${filePath}`);

    const content = await read(filePath, { encoding: 'utf8' });
    debug(`Read content: ${content}`);

    await write(outputPath, `Processed: ${content.toUpperCase()}`, 'utf8');
    debug(`Transformed and written to ${outputPath}`);
  } catch (error) {
    console.error('An error occurred:', error);
    debug('Example failed.', 'error');
  }
  debug('SBG Utility example finished.');
}

runUtilityExample();

view raw JSON →