ts-common

Reusable generic typescript utilities, types, constants, helpers

Note: The default export is pure TypeScript and environment-agnostic—it has no dependency on Node.js, browser, or React Native APIs, so the same code runs in any of these runtimes. Subpath imports such as @lichens-innovation/ts-common/web target a specific environment and rely on its APIs.

Table of content

• ts-common
  • Prerequisites
  • Scripts
  • Optional modules
    • Excel (@lichens-innovation/ts-common/excel)
    • CSV (@lichens-innovation/ts-common/csv)
    • PDF (@lichens-innovation/ts-common/pdf)
    • Web (@lichens-innovation/ts-common/web)
    • MIME (@lichens-innovation/ts-common/mime)
    • Logger (@lichens-innovation/ts-common/logger)
    • RJSF (@lichens-innovation/ts-common/rjsf)
  • Contributions
  • Unit tests
  • Library semantic versioning
  • Project coding guidelines
  • TODOs
  • License

Prerequisites

• Node.js (>=20.x)
• Bun (>=1.2.0)

Scripts

| Command | Description | | ----------------------- | --------------------------------------------------------------------- | | bun run prepare | Configures Husky (Git hooks). Runs automatically after bun install. | | bun run build | Compiles the project with tsup (outputs to dist/). | | bun run clean:node | Removes node_modules and bun.lockb. | | bun run clean:dist | Removes the dist directory. | | bun run typecheck | Type-checks TypeScript without emitting files (tsc --noEmit). | | bun run lint | Runs ESLint on the project. | | bun run lint:fix | Runs ESLint and applies automatic fixes. | | bun run test | Runs tests with Vitest and coverage report. | | bun run test:watch | Runs tests in watch mode with Vitest. | | bun run test:coverage | Runs tests with coverage report using Vitest. |

Optional modules

This library provides optional subpath modules with external dependencies. Install only the dependencies you need. For more information regarding the packaging, see the following technical explanation.

Excel (@lichens-innovation/ts-common/excel)

npm install exceljs mime

CSV (@lichens-innovation/ts-common/csv)

npm install papaparse mime

PDF (@lichens-innovation/ts-common/pdf)

npm install jspdf jspdf-autotable

Web (@lichens-innovation/ts-common/web)

No external dependency required.

MIME (@lichens-innovation/ts-common/mime)

npm install mime

Logger (@lichens-innovation/ts-common/logger)

Logger based on pino with formatted console output (timestamp, colored levels). Works in browser and Node.js.

• Browser: logs are formatted and sent to console with colored level labels.
• Node.js: logs are formatted with pino-pretty (colorized, readable output). Install pino-pretty when using the logger in Node.

Install the dependencies:

npm install pino

For Node.js (required for pretty output):

npm install pino-pretty

Exports: logger, setLoggerMinimumLevel, type Level.

Usage example:

import { logger, setLoggerMinimumLevel, type Level } from '@lichens-innovation/ts-common/logger';

// Minimum level (optional): "trace" | "debug" | "info" | "warn" | "error" | "fatal"
setLoggerMinimumLevel('debug');

logger.info('Simple message');
logger.debug('Debug', { userId: '123', action: 'login' });
logger.error('Error', { code: 500 });

RJSF (@lichens-innovation/ts-common/rjsf)

Utilities and hooks for React JSON Schema Form (RJSF) with i18n (i18next / react-i18next), localized validation (ajv-i18n), and form layout. For React apps using RJSF with translation and validation.

Install the dependencies:

npm install @rjsf/core @rjsf/utils @rjsf/validator-ajv8 ajv-i18n i18next react-i18next

Contributions

Contributions to the project are made by simply improving the current codebase and then creating a Pull Request. When the PR is merged into main, the CI pipeline runs automatically. semantic-release determines the next version from conventional commit messages, updates CHANGELOG.md and package.json, and publishes the new version to the GitHub Packages registry — no manual version bump required.

Unit tests

Test coverage must be maintained at 80% or higher. It is therefore important to always attempt to cover new code that is added with appropriate tests.

Library semantic versioning

Versioning is automated by semantic-release using Conventional Commits. The release type is derived from commit message prefixes:

| Commit prefix | Release type | | ----------------------------- | ----------------------------------------------- | | fix: | PATCH — backward-compatible bug fix | | feat: | MINOR — new backward-compatible functionality | | feat!: / BREAKING CHANGE: | MAJOR — incompatible API change |

Follow Semantic Versioning (MAJOR.MINOR.PATCH) when writing commit messages — the tooling takes care of the rest.

Project coding guidelines

Adhering to established coding guidelines is essential for developing efficient, maintainable, and scalable software. These guidelines promote consistency across codebases, making it easier for teams to collaborate and for new developers to understand existing code. By following standardized patterns, such as those outlined in the Coding guidelines, developers can reduce errors and enhance code readability.

• Coding guidelines

TODOs

This section list remaining tasks (not yet completed)

• RJSF-001: find a way to dynamically resolve the rjsf-i18n.utils "%1 Key" pattern

License

This project is licensed under the MIT License - see the LICENSE file for details.