Slonik Utilities

Common errors

• TypeError: Cannot read properties of undefined (reading 'query')

  cause The `connection` object passed to `slonik-utilities` functions is not a valid Slonik `Connection` or `Pool` instance, or it's `undefined`.
  fix Ensure you are passing a valid `Slonik` `Connection` or `Pool` instance. When using a `pool.connect()` callback, ensure you pass the `connection` argument from the callback, e.g., `const result = await pool.connect(async (connection) => update(connection, ...));`

• Error: Slonik client has not been configured.

  cause This error originates from `slonik` itself, indicating that `createPool` was not called or its connection string was invalid, preventing a proper Slonik client from being initialized.
  fix Verify your Slonik pool creation. Ensure `createPool` is called with a valid `connectionString` (e.g., `process.env.DATABASE_URL`) and that your database is accessible.

• TypeError: require() of ES Module [...] from [...] not supported.

  cause Attempting to use `require()` to import `slonik-utilities` when the package is an ES Module, or the package is not installed.
  fix Install the package (`npm install slonik-utilities`). If the error persists and you are in a Node.js project, switch to `import` statements and ensure your project is configured for ESM (e.g., `"type": "module"` in `package.json` or `.mjs` file extension).

Warnings

• breaking Slonik-utilities requires a peer dependency of `slonik` version `>28`. Mismatched Slonik versions can lead to type errors, runtime failures, or unexpected behavior due to API changes in Slonik itself.
  Fix: Ensure your `package.json` specifies `slonik: "^28.0.0"` or `"^29.0.0"` (or newer compatible versions) and run `npm install` or `yarn install`.
• breaking Since major version 2.0.0, `slonik-utilities` is published as an ESM module. Attempting to `require()` it in a CommonJS context will result in a `TypeError: require() of ES Module`.
  Fix: Use `import { ... } from 'slonik-utilities';` in an ES module context. For Node.js, ensure your `package.json` has `"type": "module"` or use a `.mjs` file extension.
• gotcha When passing named value bindings or boolean expression values, `slonik-utilities` (and Slonik by default) will automatically snake_case property names to match typical PostgreSQL column naming conventions. If your column names use a different casing (e.g., `camelCase`), you must explicitly match them or configure Slonik's naming convention transformer.
  Fix: Ensure your JavaScript property names in `namedValueBindings` and `booleanExpressionValues` match the snake_case representation of your PostgreSQL column names. For example, `givenName` in JS becomes `given_name` in SQL.
• deprecated In version 1.9.1, the library removed the `Type` suffix from its TypeScript interfaces (e.g., `UpdateResultType` became `UpdateResult`). While not a runtime breaking change, it requires updates to type imports in TypeScript projects.
  Fix: Update your TypeScript code to remove the `Type` suffix from imported types from `slonik-utilities`.

Install

• npm install slonik-utilities npm
• yarn add slonik-utilities yarn
• pnpm add slonik-utilities pnpm

Imports

• update
  wrong:

  const { update } = require('slonik-utilities');

  correct:

  import { update } from 'slonik-utilities';

  The library ships as an ESM module, requiring `import` statements. TypeScript users benefit from strong typing.
• updateDistinct
  wrong:

  const updateDistinct = require('slonik-utilities').updateDistinct;

  correct:

  import { updateDistinct } from 'slonik-utilities';

  Similar to `update`, this is a named export. It's useful for avoiding unnecessary writes when data hasn't changed by comparing distinct values.
• upsert
  wrong:

  import upsert from 'slonik-utilities';

  correct:

  import { upsert } from 'slonik-utilities';

  The `upsert` utility is a named export. Ensure your database table has appropriate unique constraints for `upsert` to function correctly.

Quickstart

Demonstrates how to use the `slonik-utilities` `update` function to modify records in a PostgreSQL database using a Slonik connection, including basic setup and verification.

import { createPool, sql } from 'slonik';
import { update } from 'slonik-utilities';

const connectionString = process.env.DATABASE_URL ?? 'postgres://user:password@localhost:5432/database';

async function runExample() {
  const pool = await createPool(connectionString);

  try {
    // Create a dummy table for demonstration
    await pool.query(sql`
      CREATE TABLE IF NOT EXISTS "user" (
        id SERIAL PRIMARY KEY,
        given_name TEXT,
        last_name TEXT
      );
    `);

    // Insert some initial data
    await pool.query(sql`
      INSERT INTO "user" (given_name, last_name) VALUES ('John', 'Doe'), ('Jane', 'Smith');
    `);

    console.log('Initial data inserted.');

    // Use slonik-utilities to update rows matching a condition
    const updateResult = await pool.connect(async (connection) => {
      return await update(
        connection,
        'user',
        {
          givenName: 'Jonathan'
        },
        {
          lastName: 'Doe'
        }
      );
    });

    console.log(`Updated ${updateResult.rowCount} row(s).`);

    // Verify the update
    const updatedUsers = await pool.query(sql`SELECT * FROM "user" WHERE last_name = 'Doe'`);
    console.log('Updated user:', updatedUsers.rows[0]);

  } catch (error) {
    console.error('Error during example execution:', error);
  } finally {
    await pool.end();
  }
}

runExample();