Joye Backend Utility

7.4.1 verified Thu Apr 23 auth: no javascript

The `joye-backend-utility` package provides a collection of common functions and database-related generic utilities specifically designed for backend services within the Joye ecosystem. It aims to streamline repetitive tasks and provide a consistent interface for database interactions and other core backend logic. Currently at version 7.4.1, the package ships with TypeScript types, indicating a focus on type safety and developer experience in TypeScript projects. While its release cadence is not publicly documented, the version number suggests a mature library. A key differentiator is its integration with Joye's specific backend architecture, which might include particular database setups or service patterns. Users should be aware of its dependency on Node.js 17.1.0 as specified in its `engines` field, which is an older, end-of-life Node.js version.

Common errors

error Error: The package 'joye-backend-utility' was installed for an incompatible Node.js version. Expected '17.1.0' but found '20.x.x'. ↓

cause The `engines` field in `package.json` specifies Node.js 17.1.0, but the current environment is running a different, likely newer, version of Node.js.

fix

Either switch your Node.js version manager (e.g., nvm use 17.1.0) to match the required engine version, or use the --ignore-engines flag with npm (npm install --ignore-engines) or yarn (yarn install --ignore-engines) at your own risk. The latter may lead to unexpected runtime issues.

error TypeError: (0 , joye_backend_utility__WEBPACK_IMPORTED_MODULE_0__.initDatabase) is not a function ↓

cause This error typically occurs in a bundled environment (e.g., Webpack, Vite) or when using `require()` with an ESM-only package. It indicates that `initDatabase` was not correctly resolved as a named export.

fix

Ensure you are using ES module import { initDatabase } from 'joye-backend-utility'; syntax. If using CommonJS, consider refactoring to ESM or using a dynamic import() call. If bundling, verify your bundler's configuration supports ESM correctly for Node.js packages.

error Error: Database connection failed: self-signed certificate in certificate chain ↓

cause The package, when connecting to a database, is encountering an SSL/TLS certificate validation error, often in development environments where self-signed certificates are used without proper trust configuration.

fix

For development, you might set an environment variable like NODE_TLS_REJECT_UNAUTHORIZED='0' (use with extreme caution in production). Alternatively, configure your database client to accept a specific CA certificate or disable SSL verification if appropriate for your environment and security policy. Consult your database client's documentation for specific connection options.

Warnings

breaking The package explicitly lists `"node": "17.1.0"` in its `engines` field. Node.js 17.x is an end-of-life (EOL) release and is not actively maintained. Running this package on newer LTS Node.js versions (e.g., 18, 20, 22) may lead to unexpected runtime errors, dependency conflicts, or module resolution issues. ↓

fix It is highly recommended to test the package thoroughly on your target Node.js LTS version. If issues arise, consider either pinning your project to Node.js 17.1.0 (not recommended for production) or submitting an issue/PR to the package maintainers to update engine compatibility and address any breaking changes.

gotcha The README includes `npm login` and `npm publish` commands. These commands are intended for package maintainers to publish new versions, not for end-users installing or using the package. Following these instructions as a user will not install the package and might lead to confusion. ↓

fix To install the package, use `npm install joye-backend-utility` or `yarn add joye-backend-utility`. Disregard the `npm login` and `npm publish` commands unless you are a maintainer of this specific package.

gotcha Being a 'Joye backend utility', this package is likely highly specialized for the internal architecture and conventions of the Joye ecosystem. While it provides generic database and common functions, certain behaviors or assumptions might be deeply tied to Joye's specific setup, potentially limiting its reusability in generic projects without significant adaptation. ↓

fix Review the source code or documentation thoroughly to understand any implicit dependencies or architectural assumptions if integrating this package into a non-Joye project. Be prepared to implement adapters or alternative logic for Joye-specific integrations.

Install

npm install joye-backend-utility

yarn add joye-backend-utility

pnpm add joye-backend-utility

Imports

initDatabase
wrong
```
const { initDatabase } = require('joye-backend-utility');
```
correct
```
import { initDatabase } from 'joye-backend-utility';
```
The library primarily uses ES Module syntax. CommonJS `require` may lead to module resolution errors, especially on Node.js versions newer than 17.x. Specific function names like `initDatabase` are illustrative examples.
queryBuilder
wrong
```
import * as JoyeUtils from 'joye-backend-utility';
```
correct
```
import { queryBuilder, commonUtils } from 'joye-backend-utility';
```
Most functionalities are exported as named exports. Avoid importing the entire module namespace unless explicitly required, as it might pull in unnecessary code.
JoyeDbConfig
```
import type { JoyeDbConfig } from 'joye-backend-utility';
```
TypeScript types are available for configuration objects and function signatures. Always use `import type` for type-only imports to ensure they are stripped during compilation and do not cause runtime overhead.

Quickstart

This quickstart demonstrates initializing the database connection, using a hypothetical common utility function, and executing a simple parameterized query. It showcases basic setup and interaction patterns.

import { initDatabase, executeQuery, commonUtils } from 'joye-backend-utility';

interface MyDbConfig {
  host: string;
  port: number;
  user: string;
  password?: string;
  database: string;
}

interface User {
  id: string;
  name: string;
  email: string;
}

async function bootstrapApp() {
  const dbConfig: MyDbConfig = {
    host: process.env.DB_HOST ?? 'localhost',
    port: parseInt(process.env.DB_PORT ?? '5432'),
    user: process.env.DB_USER ?? 'admin',
    password: process.env.DB_PASSWORD,
    database: process.env.DB_NAME ?? 'joye_app'
  };

  try {
    // Initialize the database connection pool or client
    await initDatabase(dbConfig);
    console.log('Database initialized successfully.');

    // Example: Use a common utility function (hypothetical)
    const formattedName = commonUtils.formatName('john', 'doe');
    console.log(`Formatted name: ${formattedName}`);

    // Example: Execute a simple query
    const users = await executeQuery<User[]>('SELECT id, name, email FROM users WHERE active = $1', [true]);
    console.log('Fetched users:', users);

  } catch (error) {
    console.error('Failed to initialize or interact with the database:', error);
    process.exit(1);
  }
}

bootstrapApp();