Skip to content

docs: add use cases and clearer examples #10

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
calvinbrewer merged 4 commits into from
Dec 10, 2024
Merged

docs: add use cases and clearer examples #10

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
4 commits
Select commit Hold shift + click to select a range
58f6341
docs: add use cases and clearer examples
calvinbrewer Dec 10, 2024
9f7f483
docs: spelling mistake
calvinbrewer Dec 10, 2024
ce0da24
docs: add examples
calvinbrewer Dec 10, 2024
a2a2a15
docs: add examples
calvinbrewer Dec 10, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
0 CONTRIBUTING.md → CONTRIBUTE.md
View file
Open in desktop
File renamed without changes.
30 changes: 26 additions & 4 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,24 +12,36 @@
- [createEqlPayload](#createeqlpayload)
- [getPlaintext](#getplaintext)
- [Logging](#logging)
- [Examples](#examples)
- [Releasing new versions](#releasing-new-versions)
- [Contributing](#contributing)
- [License](#license)

## Features

`jseql` leverages [Encrypt Query Language (EQL)](https://github.com/cipherstash/encrypt-query-language) and [CipherStash](https://cipherstash.com) to encrypt data in a PostgreSQL database.

**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](https://github.com/logtape/logtape) for debugging and monitoring.

**Use cases:**
- Meet compliance requirements for data encryption in your application.
- Ensure only the intended users can access sensitive data.
- Exceed customer expectations for data security.
- Improve your overall security posture and reduce the risk of data breaches.

## Installation

Install `jseql` via one of the following methods:

```bash
npm install @cipherstash/jseql
# or
yarn add @cipherstash/jseql
# or
bun add @cipherstash/jseql
```

Expand Down Expand Up @@ -67,10 +79,11 @@ const payload = createEqlPayload({
table: 'messages',
column: 'content',
})
console.log(payload)

sql = `INSERT INTO messages (content) VALUES (${payload});`
```

**Output:**
**Payload:**

```json
{
Expand All @@ -88,7 +101,7 @@ console.log(payload)

#### getPlaintext

Extracts the plaintext data from an EQL payload.
Extracts the plaintext data from an EQL payload which has been decrypted.

**Parameters:**

Expand All @@ -112,6 +125,8 @@ const payload = {
const plaintext = getPlaintext(payload)
console.log(plaintext) // Output: 'Hello, World!'
```
> [!TIP]
> Note: the payload that is stored in the database is encrypted, so it is not possible to view the plaintext data directly even if you have direct access to the database as an administrator.

### Logging

Expand Down Expand Up @@ -158,6 +173,13 @@ const payload = createEqlPayload({

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

## Examples

- [Drizzle](/apps/drizzle)
- [Prisma](/apps/prisma)

`jseql` can be used with most ORMs that support PostgreSQL. If you're interested in using `jseql` with a specific ORM, please [create an issue](https://github.com/cipherstash/jseql/issues/new).

## Releasing new versions

We use [Changesets](https://github.com/changesets/changesets) to manage our releases.
Expand All @@ -175,7 +197,7 @@ Create a pull request and merge it into the `main` branch, which will trigger th

## Contributing

Please see the [CONTRIBUTING.md](CONTRIBUTING.md) file for more information.
Please see the [CONTRIBUTE.md](CONTRIBUTE.md) file for more information.

## License

Expand Down