jseql

jseql is a JavaScript/TypeScript package designed to facilitate interaction with Encrypt Query Language (EQL). It provides classes and methods to encode and decode values when working with encrypted data in a PostgreSQL database.

Table of Contents

• Features
• Installation
• Usage
  • Importing the package
  • Functions
    • createEqlPayload
    • getPlaintext
  • Logging
• Releasing new versions
• Contributing
• License

Features

• Data encoding: Easily create EQL payloads with the createEqlPayload function.
• Data decoding: Extract plaintext data from EQL payloads using getPlaintext.
• TypeScript support: Strongly typed with TypeScript interfaces and types.
• Logging: Integrated logging using logtape for debugging and monitoring.

Installation

Install jseql via one of the following methods:

npm install @cipherstash/jseql
yarn add @cipherstash/jseql
bun add @cipherstash/jseql

Usage

Importing the package

import {
  createEqlPayload,
  getPlaintext,
  type CsPlaintextV1Schema,
} from '@cipherstash/jseql'

Functions

createEqlPayload

Creates an EQL payload which is required for database operations with encrypted data.

Parameters:

• plaintext (string | undefined): The plaintext data to include in the payload.
• table (string): The database table name.
• column (string): The column name in the table.
• version (number, optional): The version of the payload. Defaults to 1.
• queryType (string | null, optional): The query type. Defaults to null.

Usage:

const payload = createEqlPayload({
  plaintext: 'Hello, World!',
  table: 'messages',
  column: 'content',
})
console.log(payload)

Output:

{
  "v": 1,
  "s": 1,
  "k": "pt",
  "p": "Hello, World!",
  "i": {
    "t": "messages",
    "c": "content"
  },
  "q": null
}

getPlaintext

Extracts the plaintext data from an EQL payload.

Parameters:

• payload (CsPlaintextV1Schema | null): The EQL payload.

Returns:

• string | undefined: The plaintext data if available.

Usage:

const payload = {
  v: 1,
  s: 1,
  k: 'pt',
  p: 'Hello, World!',
  i: { t: 'messages', c: 'content' },
  q: null,
}
const plaintext = getPlaintext(payload)
console.log(plaintext) // Output: 'Hello, World!'

Logging

jseql uses logtape for logging, which allows you to control the logging output and integrate it with your application's logging system.

To set up logging for jseql, you need to configure a sink for the 'jseql' logger.

Setup Example:

// Configure the logger
import { configure, getConsoleSink, getFileSink } from '@logtape/logtape'

await configure({
  sinks: {
    console: getConsoleSink(),
  },
  loggers: [
    {
      category: ['jseql'],
      level: 'debug',
      sinks: ['console'],
    },
  ],
})

// Use jseql functions as usual
import { createEqlPayload } from 'jseql'

const payload = createEqlPayload({
  plaintext: 'Secret Data',
  table: 'users',
  column: 'password',
})

// The logger will output debug information to the console

Output:

[debug] [jseql] Creating the EQL payload { ...payload data... }

By setting up the logger, you can monitor the internal operations of jseql, which is especially useful for debugging and development purposes.

Releasing new versions

We use Changesets to manage our releases. To create a new release, run the following command:

bun changeset

Create a pull request and merge it into the main branch, which will trigger the release workflow.

1. Changesets will open a new pull request with the new version.
2. Merge the pull request into the main branch.
3. Changesets will automatically publish the new version to npm.

Contributing

Please see the CONTRIBUTING.md file for more information.

License

Please see the LICENSE file for more information.