Skip to content

quickstart.md

Latest commit

 

History

History
124 lines (93 loc) · 2.75 KB

quickstart.md

File metadata and controls

124 lines (93 loc) · 2.75 KB

Quick Start

Installation

npm install @opendecree/sdk

Connect to the Server

import { ConfigClient } from '@opendecree/sdk';

const client = new ConfigClient('localhost:9090', { subject: 'myapp' });

The subject identifies your application in audit logs. For production setups with JWT authentication, pass a token instead:

const client = new ConfigClient('localhost:9090', { token: 'eyJhbG...' });

Get and Set Values

try {
  // Read a string value (default type)
  const fee = await client.get('tenant-id', 'payments.fee');
  console.log(fee); // "0.5%"

  // Write a value
  await client.set('tenant-id', 'payments.fee', '1.0%');
} finally {
  client.close();
}

Typed Gets

Pass a built-in constructor as the third argument to convert the value at runtime. The return type narrows automatically.

const retries = await client.get('tenant-id', 'payments.retries', Number);
// retries: number

const enabled = await client.get('tenant-id', 'payments.enabled', Boolean);
// enabled: boolean

const name = await client.get('tenant-id', 'payments.name', String);
// name: string (explicit, same as default)

Nullable Gets

Some fields may not have a value set. By default, get() throws a NotFoundError. Pass { nullable: true } to return null instead:

const fee = await client.get('tenant-id', 'payments.fee', Number, {
  nullable: true,
});
// fee: number | null

Set Multiple Values Atomically

await client.setMany('tenant-id', {
  'payments.fee': '0.5%',
  'payments.retries': '3',
  'payments.enabled': 'true',
});

Clear a Value

await client.setNull('tenant-id', 'payments.fee');

Error Handling

All SDK errors extend DecreeError. Catch specific error types for fine-grained control:

import {
  NotFoundError,
  InvalidArgumentError,
  PermissionDeniedError,
  UnavailableError,
} from '@opendecree/sdk';

try {
  await client.get('tenant-id', 'missing.field');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.log('Field not found');
  } else if (err instanceof UnavailableError) {
    console.log('Server unreachable');
  } else {
    throw err;
  }
}

Dispose Pattern (TypeScript 5.2+)

ConfigClient supports Symbol.dispose, so you can use the using declaration for automatic cleanup:

{
  using client = new ConfigClient('localhost:9090', { subject: 'myapp' });
  const fee = await client.get('tenant-id', 'payments.fee');
} // client.close() called automatically

Next Steps

  • Configuration -- all client options, auth, TLS, retry, and timeouts
  • Watching -- live config subscriptions with ConfigWatcher and WatchedField