diff --git a/README.template.md b/README.template.md index 1acc393..fd89fb6 100644 --- a/README.template.md +++ b/README.template.md @@ -1,14 +1,20 @@ {{ ossHeader }} -# Momento Node.js multi-region writer client +# Momento Node.js Multi-Region Writer Client ## What and why? -This project provides multi-region write capabilities to the for the [Momento Node.js SDK](https://github.com/momentohq/client-sdk-javascript). +The Momento Node.js Multi-Region Writer Client enables turnkey multi-region write operations uisng the [Momento Node.js SDK](https://github.com/momentohq/client-sdk-javascript). If your application requires cross-region writes to improve availability, reduce latency, or meet geographic data residency requirements, this SDK is designed for you. + +## Key Features + +- **Multi-region support**: Write to multiple regions in parallel with a single API call. +- **Granular response handling**: Distinguish between successful and failed writes across regions. +- **Familiar interface**: Easily port code written with the Momento Node.js SDK. ## Installation -The Momento Node.js multi-region write client is [available on npm.js](https://www.npmjs.com/package/@gomomento-poc/sdk-multi-region). You can install it via: +The client is [available on npm.js](https://www.npmjs.com/package/@gomomento-poc/sdk-multi-region). You can install it via: ```bash npm install @gomomento-poc/sdk-multi-region @@ -16,6 +22,19 @@ npm install @gomomento-poc/sdk-multi-region ## Usage -TODO +Using the multi-region writer client is similar to the [Momento Node.js SDK](https://docs.momentohq.com/platform/sdks/nodejs/cache), with additional configuration for multi-region operations: + +1. **Specify regions and credentials**: Provide API keys for each region you want to write to. +2. **Configure the multi-region client**: Provide a single Momento Node.js [Configuration](https://docs.momentohq.com/cache/develop/basics/client-configuration-objects) object that will be used identically across all regions. +3. **Handle multi-region responses**: Use built-in accessors to inspect successes and errors across regions. + +Here's an example of how to use the SDK: + +```typescript +{%include "./examples/multi-region.ts" %} +``` + +> [!TIP] +> Configure the client timeout to accommodate network latencies between your application and the farthest region. Since the API call waits for all writes to complete before returning, the timeout must account for the region with the longest round-trip time. Use `.withClientTimeoutMillis` on the configuration to adjust this. {{ ossFooter }} diff --git a/examples/multi-region.ts b/examples/multi-region.ts index f6194a9..e7d688c 100644 --- a/examples/multi-region.ts +++ b/examples/multi-region.ts @@ -2,13 +2,12 @@ import { Configurations, CredentialProvider, MultiRegionCacheSetResponse, - MultiRegionCacheSortedSetPutElementsResponse, MultiRegionCacheWriterClient, } from '@gomomento-poc/sdk-multi-region'; async function main(): Promise { - const cacheName = process.env.MOMENTO_CACHE_NAME ?? 'test-cache'; const client = new MultiRegionCacheWriterClient({ + // Can provide meaningful names for each region credentialProviders: { 'region-1': CredentialProvider.fromEnvVar('MOMENTO_API_KEY_REGION_1'), 'region-2': CredentialProvider.fromEnvVar('MOMENTO_API_KEY_REGION_2'), @@ -16,6 +15,7 @@ async function main(): Promise { configuration: Configurations.Laptop.latest(), defaultTtlSeconds: 60, }); + const cacheName = process.env.MOMENTO_CACHE_NAME ?? 'cache'; const setResponse = await client.set(cacheName, 'scalar', 'value'); switch (setResponse.type) { @@ -24,31 +24,18 @@ async function main(): Promise { break; case MultiRegionCacheSetResponse.Error: console.error( - `Found {${Object.keys(setResponse.errors()).length}} errors and {${ + `Found ${Object.keys(setResponse.errors()).length} errors and ${ Object.keys(setResponse.successes()).length - }} successes. The full results are: ${setResponse.toString()}` - ); - break; - } - - const sortedSetResponse = await client.sortedSetPutElements(cacheName, 'sorted-set', { - element1: 1, - element2: 2, - }); - switch (sortedSetResponse.type) { - case MultiRegionCacheSortedSetPutElementsResponse.Success: - console.log('Success:', sortedSetResponse.results()); - break; - case MultiRegionCacheSortedSetPutElementsResponse.Error: - console.error( - `Found {${Object.keys(sortedSetResponse.errors()).length}} errors and {${ - Object.keys(sortedSetResponse.successes()).length - }} successes. The full results are: ${setResponse.toString()}` + } successes. Errors:` ); + // Handle regional write errors as needed + for (const [region, error] of Object.entries(setResponse.errors())) { + console.error(`- ${region}: ${error.toString()}`); + } break; } } main() .then(() => console.log('done')) - .catch(console.error); + .catch(err => console.error(err));