|
1 | | -# OpenFeature SDK for JavaScript |
| 1 | +# OpenFeature JavaScript SDKs |
2 | 2 |
|
3 | 3 | [](https://cloud-native.slack.com/archives/C0344AANLA1) |
| 4 | +[](https://snyk.io/test/github/open-feature/js-sdk) |
4 | 5 | [](https://codecov.io/gh/open-feature/js-sdk) |
| 6 | +[](https://bestpractices.coreinfrastructure.org/projects/6594) |
| 7 | + |
| 8 | +This repository contains the JavaScript implementations of [OpenFeature][openfeature-website], a vendor-agnostic abstraction library for evaluating feature flags. |
| 9 | + |
| 10 | +We support multiple data types for flags (numbers, strings, booleans, objects) as well as hooks, which can alter the lifecycle of a flag evaluation. |
| 11 | + |
| 12 | +## Server |
| 13 | + |
| 14 | +--- |
| 15 | + |
5 | 16 | [](https://badge.fury.io/js/@openfeature%2Fjs-sdk) |
6 | | -[](https://snyk.io/test/github/open-feature/js-sdk) |
7 | 17 | [](https://github.com/open-feature/spec/tree/v0.5.1) |
8 | | -[](https://bestpractices.coreinfrastructure.org/projects/6594) |
9 | 18 |
|
10 | 19 | <p align="center"> |
11 | 20 | <strong> |
| 21 | + <!-- TODO: add direct link to server module when published --> |
12 | 22 | <a href="https://docs.openfeature.dev/docs/tutorials/getting-started/node">Getting Started<a/> |
13 | 23 | • |
14 | 24 | <a href="https://open-feature.github.io/js-sdk">API Documentation<a/> |
|
17 | 27 |
|
18 | 28 | --- |
19 | 29 |
|
20 | | -This is the JavaScript implementation of [OpenFeature][openfeature-website], a vendor-agnostic abstraction library for evaluating feature flags. |
21 | | - |
22 | | -We support multiple data types for flags (numbers, strings, booleans, objects) as well as hooks, which can alter the lifecycle of a flag evaluation. |
23 | | - |
24 | | -> This library is intended to be used in server-side contexts and has only **experimental support** for web usage. Client-side support can be tracked [here][client-side-github-issue]. |
25 | | -
|
26 | | -## Installation |
| 30 | +### Installation |
27 | 31 |
|
28 | 32 | ```shell |
29 | 33 | npm install @openfeature/js-sdk |
|
35 | 39 | yarn add @openfeature/js-sdk |
36 | 40 | ``` |
37 | 41 |
|
38 | | -## Usage |
39 | | - |
40 | | -To configure the SDK you'll need to add a provider to the `OpenFeature` global signleton. From there, you can generate a `client` which is usable by your code. While you'll likely want a provider for your specific backend, we've provided a `NoopProvider`, which simply returns the default value. |
41 | | - |
42 | | -```typescript |
43 | | -import { OpenFeature } from '@openfeature/js-sdk'; |
44 | | - |
45 | | -// configure a provider |
46 | | -OpenFeature.setProvider(new YourProviderOfChoice()); |
47 | | - |
48 | | -// create a client |
49 | | -const client = OpenFeature.getClient('my-app'); |
50 | | - |
51 | | -// get a bool value |
52 | | -const boolValue = await client.getBooleanValue('boolFlag', false); |
53 | | - |
54 | | -// get a string value |
55 | | -const stringValue = await client.getStringValue('stringFlag', 'default'); |
56 | | - |
57 | | -// get an numeric value |
58 | | -const numberValue = await client.getNumberValue('intFlag', 1); |
59 | | - |
60 | | -// get an object value |
61 | | -const object = await client.getObjectValue<MyObject>('objectFlag', {}); |
62 | | - |
63 | | -// add a value to the invocation context |
64 | | -const context: EvaluationContext = { |
65 | | - myInvocationKey: 'myInvocationValue', |
66 | | -}; |
67 | | -const contextAwareValue = await client.getBooleanValue('boolFlag', false, context); |
68 | | -``` |
69 | | - |
70 | | -A list of available providers can be found [here][server-side-artifacts]. |
71 | | - |
72 | | -For complete documentation, visit: https://docs.openfeature.dev/docs/category/concepts |
73 | | - |
74 | | -## Hooks |
75 | | - |
76 | | -Implement your own hook by conforming to the [Hook interface][hook-interface]. |
77 | | - |
78 | | -All of the hook stages (before, after, error, and finally) are optional. |
79 | | - |
80 | | -```typescript |
81 | | -import { OpenFeature, Hook, HookContext } from '@openfeature/js-sdk'; |
82 | | - |
83 | | -// Example hook that logs if an error occurs during flag evaluation |
84 | | -export class GlobalDebugHook implements Hook { |
85 | | - after(hookContext: HookContext, err: Error) { |
86 | | - console.log('hook context', hookContext); |
87 | | - console.error(err); |
88 | | - } |
89 | | -} |
90 | | -``` |
91 | | - |
92 | | -Register the hook at global, client, or invocation level. |
93 | | - |
94 | | -```typescript |
95 | | -import { OpenFeature } from '@openfeature/js-sdk'; |
96 | | -// This hook used is used for example purposes |
97 | | -import { GlobalDebugHook, ClientDebugHook, InvocationDebugHook } from './debug-hook'; |
98 | | - |
99 | | -// A global hook will run on every flag evaluation |
100 | | -OpenFeature.addHooks(new GlobalDebugHook()); |
101 | | - |
102 | | -const client = OpenFeature.getClient('my-app'); |
103 | | -// A client hook will run on every flag evaluation executed by this client |
104 | | -client.addHooks(new ClientDebugHook()); |
105 | | - |
106 | | -// An invocation hook will only run on the registred flag evaluation method |
107 | | -const boolValue = await client.getBooleanValue('boolFlag', false, {}, { hooks: [new InvocationDebugHook()] }); |
108 | | -``` |
109 | | - |
110 | | -A list of available hooks can be found [here][server-side-artifacts]. |
| 42 | +See [README.md](./packages/server/README.md) |
111 | 43 |
|
112 | 44 | ## Contributing |
113 | 45 |
|
|
0 commit comments