Merge pull request #119 from cipherstash/bulk-models

Author: calvinbrewer

.changeset/every-dryers-wink.md

@@ -0,0 +1,5 @@
+---
+"@cipherstash/protect": major
+---
+
+Replaced bulk operations with model operations.

docs/README.md

@@ -11,9 +11,9 @@ The documentation for Protect.js is organized into the following sections:
 ## Reference
 
 - [Configuration and production deployment](./reference/configuration.md)
-- [Bulk encryption and decryption](./reference/bulk-encryption-decryption.md)
 - [Searchable encryption with PostgreSQL](./reference/searchable-encryption-postgres.md)
 - [Protect.js schemas](./reference/schema.md)
+- [Model operations with bulk crypto functions](./reference/model-operations.md)
 
 ## How-to guides
 

docs/getting-started.md

@@ -5,11 +5,12 @@ This getting started guide steps you through:
 1. Installing and configuring Protect.js in a standalone project
 2. Encrypting, searching, and decrypting data in a PostgreSQL database
 
-> [!IMPORTANT]
+> [!IMPORTANT] 
 > **Prerequisites:** Before you start you need to have this software installed:
->  - [Node.js](https://nodejs.org/)
->  - [TypeScript](https://www.typescriptlang.org/)
->  - [PostgreSQL](https://www.postgresql.org/) — see PostgreSQL's [documentation for installing](https://www.postgresql.org/download/)
+>
+> - [Node.js](https://nodejs.org/)
+> - [TypeScript](https://www.typescriptlang.org/)
+> - [PostgreSQL](https://www.postgresql.org/) — see PostgreSQL's [documentation for installing](https://www.postgresql.org/download/)
 
 ### Step 0: Basic file structure
 
@@ -65,10 +66,10 @@ Lastly, install the CipherStash CLI:
   ```
 
 - On Linux, download the binary for your platform, and put it on your `PATH`:
-    - [Linux ARM64](https://github.com/cipherstash/cli-releases/releases/latest/download/stash-aarch64-unknown-linux-gnu)
-    - [Linux x86_64](https://github.com/cipherstash/cli-releases/releases/latest/download/stash-x86_64-unknown-linux-gnu)
+  - [Linux ARM64](https://github.com/cipherstash/cli-releases/releases/latest/download/stash-aarch64-unknown-linux-gnu)
+  - [Linux x86_64](https://github.com/cipherstash/cli-releases/releases/latest/download/stash-x86_64-unknown-linux-gnu)
 
-> [!NOTE]
+> [!NOTE] 
 > **You need to opt out of bundling when using Protect.js.**
 >
 > Protect.js uses Node.js specific features and requires the use of the [native Node.js `require`](https://nodejs.org/api/modules.html#requireid).
@@ -108,31 +109,31 @@ Protect.js uses a schema to define the tables and columns that you want to encry
 To define your tables and columns, add the following to `src/protect/schema.ts`:
 
 ```ts
-import { csTable, csColumn } from '@cipherstash/protect'
+import { csTable, csColumn } from "@cipherstash/protect";
 
-export const users = csTable('users', {
-  email: csColumn('email'),
-})
+export const users = csTable("users", {
+  email: csColumn("email"),
+});
 
-export const orders = csTable('orders', {
-  address: csColumn('address'),
-})
+export const orders = csTable("orders", {
+  address: csColumn("address"),
+});
 ```
 
 **Searchable encryption:**
 
 If you want to search encrypted data in your PostgreSQL database, you must declare the indexes in schema in `src/protect/schema.ts`:
 
 ```ts
-import { csTable, csColumn } from '@cipherstash/protect'
+import { csTable, csColumn } from "@cipherstash/protect";
 
-export const users = csTable('users', {
-  email: csColumn('email').freeTextSearch().equality().orderAndRange(),
-})
+export const users = csTable("users", {
+  email: csColumn("email").freeTextSearch().equality().orderAndRange(),
+});
 
-export const orders = csTable('orders', {
-  address: csColumn('address'),
-})
+export const orders = csTable("orders", {
+  address: csColumn("address"),
+});
 ```
 
 Read more about [defining your schema](./docs/reference/schema.md).
@@ -142,11 +143,11 @@ Read more about [defining your schema](./docs/reference/schema.md).
 To import the `protect` function and initialize a client with your defined schema, add the following to `src/protect/index.ts`:
 
 ```ts
-import { protect } from '@cipherstash/protect'
-import { users, orders } from './schema'
+import { protect } from "@cipherstash/protect";
+import { users, orders } from "./schema";
 
 // Pass all your tables to the protect function to initialize the client
-export const protectClient = await protect(users, orders)
+export const protectClient = await protect(users, orders);
 ```
 
 The `protect` function requires at least one `csTable` to be provided.
@@ -159,21 +160,25 @@ Protect.js provides the `encrypt` function on `protectClient` to encrypt data.
 Start encrypting data by adding this to `src/index.ts`:
 
 ```typescript
-import { users } from './protect/schema'
-import { protectClient } from './protect'
+import { users } from "./protect/schema";
+import { protectClient } from "./protect";
 
-const encryptResult = await protectClient.encrypt('secret@squirrel.example', {
+const encryptResult = await protectClient.encrypt("secret@squirrel.example", {
   column: users.email,
   table: users,
-})
+});
 
 if (encryptResult.failure) {
   // Handle the failure
-  console.log("error when encrypting:", encryptResult.failure.type, encryptResult.failure.message)
+  console.log(
+    "error when encrypting:",
+    encryptResult.failure.type,
+    encryptResult.failure.message
+  );
 }
 
-const ciphertext = encryptResult.data
-console.log("ciphertext:", ciphertext)
+const ciphertext = encryptResult.data;
+console.log("ciphertext:", ciphertext);
 ```
 
 Run this with:
@@ -203,23 +208,23 @@ The `encryptResult` will return one of the following:
 ```
 
 > [!TIP]
-> Get significantly better encryption performance by using the [`bulkEncrypt` function](#bulk-encrypting-data) for large payloads.
+> Working with large payloads? Check out the [model operations with bulk cryptography functions](./reference/model-operations.md) docs.
 
 ### Step 6: Decrypt data
 
 Use the `decrypt` function to decrypt data.
 `decrypt` takes an encrypted data object as a parameter.
 
 ```typescript
-import { protectClient } from './protect'
+import { protectClient } from "./protect";
 
-const decryptResult = await protectClient.decrypt(ciphertext)
+const decryptResult = await protectClient.decrypt(ciphertext);
 
 if (decryptResult.failure) {
   // Handle the failure
 }
 
-const plaintext = decryptResult.data
+const plaintext = decryptResult.data;
 ```
 
 The `decrypt` function returns a `Result` object with either a `data` key, or a `failure` key.
@@ -241,7 +246,7 @@ The `decryptResult` will return one of the following:
 ```
 
 > [!TIP]
-> Get significantly better decryption performance by using the [`bulkDecrypt` function](#bulk-decrypting-data) for large payloads.
+> Working with large payloads? Check out the [model operations with bulk cryptography functions](./reference/model-operations.md) docs.
 
 ### Step 7: Store encrypted data in a database