Cherto TypeScript Client Library

A TypeScript/JavaScript library for querying feature flags from a Cherto feature flag service. Supports caching with automatic refresh and provides type-safe flag retrieval.

Features

• Caching with automatic periodic refresh
• Type-safe flag retrieval (boolean, string)
• Default value support
• Async/await API for modern JavaScript/TypeScript
• Browser and Node.js compatible

Installation

npm install @arthur-cherto/client

Usage

Basic Usage

import { FeatureFlagClient } from '@arthur-cherto/client';

// Recommended: scope requests to your organisation
// For production: use https://api.getcherto.com
// For local development: use http://localhost:8080
const client = new FeatureFlagClient({
  baseUrl: 'https://api.getcherto.com',  // or 'http://localhost:8080' for local dev
  organisationId: 'acme-co',
  refreshIntervalSeconds: 60, // optional (defaults to 30s)
});

// Legacy constructors still work and fall back to the server's default tenant
const legacyClient = new FeatureFlagClient('https://api.getcherto.com');
const legacyCustomInterval = new FeatureFlagClient('https://api.getcherto.com', 60);

// Get a boolean flag with a default value
const newFeatureEnabled = await client.getFlag('new-checkout-feature', false);

if (newFeatureEnabled) {
  console.log('New checkout feature is enabled!');
} else {
  console.log('Using legacy checkout flow');
}

// Get a string flag with a default value
const apiVersion = await client.getFlag('api-version', 'v1');
console.log(`Using API version: ${apiVersion}`);

// Manually refresh a specific flag
await client.refresh('new-checkout-feature');

// Shutdown when done (clears refresh interval)
client.shutdown();

TypeScript Type Safety

The getFlag method uses method overloading to provide type safety:

// Returns Promise<boolean>
const boolFlag: boolean = await client.getFlag('enabled', false);

// Returns Promise<string>
const strFlag: string = await client.getFlag('version', 'v1');

Caching Behavior

• Flags are cached after first fetch
• Cache has a default TTL of 5 seconds (configurable in code)
• Cache is automatically refreshed at the configured interval (default: 30 seconds)
• Manual refresh via refresh(flagKey) is available

Error Handling

If a flag is not found or an error occurs:

• The client returns the provided default value
• A warning is logged to the console
• The client continues to function normally

API Reference

FeatureFlagClient

Constructors

new FeatureFlagClient(options: FeatureFlagClientOptions)
new FeatureFlagClient(baseUrl: string, refreshIntervalSeconds?: number)

• options.baseUrl: Base URL of the Cherto feature flag service (e.g., https://api.getcherto.com for production or http://localhost:8080 for local development)
• options.organisationId: Required for multi-tenancy. Included in the X-Organisation-Id header.
• options.refreshIntervalSeconds: Optional refresh cadence in seconds (default: 30)
• options.apiKey: Optional bearer token added to the Authorization header
• options.additionalHeaders: Optional headers merged into every request
• baseUrl/refreshIntervalSeconds: Legacy overload for backwards compatibility (defaults organization to default)

Methods

getFlag(flagKey: string, defaultValue: boolean): Promise<boolean>

Gets the value of a feature flag as a boolean.

• flagKey: The key of the feature flag
• defaultValue: The default value to return if the flag is not found
• Returns: Promise<boolean> - The boolean value of the flag

getFlag(flagKey: string, defaultValue: string): Promise<string>

Gets the value of a feature flag as a string.

• flagKey: The key of the feature flag
• defaultValue: The default value to return if the flag is not found
• Returns: Promise<string> - The string value of the flag

refresh(flagKey: string): Promise<void>

Manually refreshes a specific flag from the server.

• flagKey: The key of the flag to refresh

shutdown(): void

Shuts down the client and releases resources (stops the refresh interval).

ChertoHttpService

Low-level HTTP service for fetching flags. Typically used internally, but can be used directly if needed.

Constructor

new ChertoHttpService(baseUrl: string, options?: { defaultHeaders?: Record<string, string> })

Methods

fetchFlag(flagKey: string): Promise<FlagResponse | null>

Fetches a feature flag from the server.

• flagKey: The key of the feature flag
• Returns: Promise<FlagResponse | null> - The flag response or null if not found

shutdown(): void

Shuts down the HTTP service (no-op in browser environments).

Examples

React Component

import React, { useEffect, useState } from 'react';
import { FeatureFlagClient } from '@arthur-cherto/client';

function MyComponent() {
  const [enabled, setEnabled] = useState(false);
  const client = new FeatureFlagClient({
    baseUrl: 'https://api.getcherto.com',  // or 'http://localhost:8080' for local dev
    organisationId: 'acme-co',
  });

  useEffect(() => {
    client.getFlag('new-feature', false).then(setEnabled);

    return () => {
      client.shutdown();
    };
  }, []);

  return <div>{enabled ? 'New Feature Enabled' : 'Legacy Feature'}</div>;
}

Node.js Application

import { FeatureFlagClient } from '@arthur-cherto/client';

async function main() {
  const client = new FeatureFlagClient({
    baseUrl: 'https://api.getcherto.com',  // or 'http://localhost:8080' for local dev
    organisationId: 'acme-co',
  });

  const featureEnabled = await client.getFlag('experimental-feature', false);
  
  if (featureEnabled) {
    console.log('Running experimental code path');
  }

  client.shutdown();
}

main();

Adding to Your Project

See USAGE.md for detailed instructions on:

• Installing locally for development
• Publishing to npm
• Using in React, Next.js, or vanilla JavaScript projects

Development

Building

npm run build

This compiles TypeScript to JavaScript in the dist/ directory.

Type Definitions

Type definitions are automatically generated in dist/index.d.ts.

Compatibility

• Browser: Uses native fetch API
• Node.js: Requires Node.js 18+ (with native fetch) or a fetch polyfill for older versions

License

MIT