feat: support bulk transactions

[angeloashmore]

Types of changes

• Chore (a non-breaking change which is related to package maintenance)
• Bug fix (a non-breaking change which fixes an issue)
• New feature (a non-breaking change which adds functionality)
• Breaking change (fix or feature that would cause existing functionality to change)

Description

This PR adds support for bulk transactions, which are a way to process multiple operations (insert, update, delete) in one request.

Internally, it makes use of the Types API's /bulk endpoint.

The following APIs are introduced:

• A client.bulk() method to perform multiple operations at once.
• A createBulkTransaction() helper to build a set of bulk operations.

Using client.bulk() looks like this:

import {
  createClient,
  createBulkTransaction,
} from "@prismicio/custom-types-client";

const client = createClient({
  repositoryName: "example-prismic-repo",
  token: "...",
});

const bulkTransaction = createBulkTransaction();
bulkTransaction.insertCustomType(myCustomType);
bulkTransaction.deleteSlice(mySlice);

await client.bulk(bulkTransaction);

A bulk transaction can be created from a before and after set of models using the fromDiff() method:

import { createClient, BulkTransaction } from "@prismicio/custom-types-client";

const client = createClient({
  repositoryName: "example-prismic-repo",
  token: "...",
});

const bulkTransaction = createBulkTransaction();
bulkTransaction.fromDiff(
  {
    customTypes: await client.getAllCustomTypes(),
    slices: await client.getAllSharedSlices(),
  },
  {
    customTypes: myNewCustomTypes,
    slices: myNewSlices,
  },
);

// Other operations can be performed before or after `fromDiff()`:
bulkTransaction.insertCustomType(myCustomType);
bulkTransaction.deleteSlice(mySlice);

await client.bulk(bulkTransaction);

createBulkTransaction() is recommended when using client.bulk(), but not required:

import {
  createClient,
  BulkOperationType,
} from "@prismicio/custom-types-client";

const client = createClient({
  repositoryName: "example-prismic-repo",
  token: "...",
});

await client.bulk([
  {
    type: BulkOperationType.CustomTypeInsert,
    id: myCustomType.id,
    payload: myCustomType,
  },
  {
    type: BulkOperationType.SliceDelete,
    id: mySlice.id,
    payload: { id: mySlice.id },
  },
]);

Refer to the TypeScript types to learn how to use bulk() directly.

Checklist:

• My change requires an update to the official documentation.
• All TSDoc comments are up-to-date and new ones have been added where necessary.
• All new and existing tests are passing.

[github-actions]

size-limit report 📦

Path	Size
dist/index.js	1.68 KB (+44.39% 🔺)
dist/index.cjs	2.08 KB (+43.82% 🔺)

[codecov-commenter]

Codecov Report

All modified and coverable lines are covered by tests ✅

Comparison is base (c662c3f) 100.00% compared to head (d0c4095) 100.00%.

❗ Your organization needs to install the Codecov GitHub app to enable full functionality.

Additional details and impacted files

@@            Coverage Diff             @@
##              main       #10    +/-   ##
==========================================
  Coverage   100.00%   100.00%            
==========================================
  Files            3         4     +1     
  Lines          641       918   +277     
  Branches        37        62    +25     
==========================================
+ Hits           641       918   +277     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

[bapmrl]

Excellent work Angelo!

[bapmrl]

❓ What does the API return if too many slices are sent? Are they going to end up in this details.customTypes array?

[angeloashmore]

I could be wrong, but I didn't see anything about slices in Slice Machine's /bulk error handling; SM only validates that the customTypes object is present.

Here is the type: https://github.com/prismicio/slice-machine/blob/380a5e8599a22cfae5144a11d548879cad4bf5b7/packages/manager/src/managers/prismicRepository/types.ts#L88-L98

I think this is because limitation errors should only happen if too many documents need to be deleted. Documents are only deleted if custom types are deleted, which does not concern slices.

[bapmrl]

Okay, I see. Thanks ^^

[angeloashmore]

@bapmrl Thanks for the review! I'm going to merge the PR to move forward with the GitHub integration, but feel free to reply to any of my replies and I can still make changes to the implementation.