Skip to content

Commit

Permalink
chore: add 0.6.0 examples to README.md (#441)
Browse files Browse the repository at this point in the history 
<!-- Please use this template for your pull request. -->
<!-- Please use the sections that you need and delete other sections -->

## This PR
<!-- add the description of the PR here -->

Adds examples for named providers, events and the global shutdown of
spec 0.6.0.
It does not provide an example for flag metadata, as I think an example
is not needed here.

### Related Issues
<!-- add here the GitHub issue that this PR resolves if applicable -->

Fixes #440

### Notes
<!-- any additional notes for this PR -->

### Follow-up Tasks
<!-- anything that is related to this PR but not done here should be
noted under this section -->
<!-- if there is a need for a new issue, please link it here -->

### How to test
<!-- if applicable, add testing instructions under this section -->

---------

Signed-off-by: Lukas Reining <[email protected]>
Signed-off-by: Michael Beemer <[email protected]>
Co-authored-by: Michael Beemer <[email protected]>
  • Loading branch information
@lukas-reining @beeme1mr
lukas-reining and beeme1mr authored Jun 6, 2023
1 parent 2a357c7 commit efa1a0d
Show file tree
Hide file tree
Showing 2 changed files with 136 additions and 9 deletions.
86 changes: 78 additions & 8 deletions packages/client/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@

[![Project Status: WIP – Initial development is in progress, but there has not yet been a stable, usable release suitable for the public.](https://www.repostatus.org/badges/latest/wip.svg)](https://www.repostatus.org/#wip)
[![npm version](https://badge.fury.io/js/@openfeature%2Fweb-sdk.svg)](https://www.npmjs.com/package/@openfeature/web-sdk)
[![Specification](https://img.shields.io/static/v1?label=Specification&message=v0.5.2&color=yellow)](https://github.com/open-feature/spec/tree/v0.5.2)
[![Specification](https://img.shields.io/static/v1?label=Specification&message=v0.6.0&color=yellow)](https://github.com/open-feature/spec/tree/v0.6.0)

## 🧪 This SDK is experimental

Expand All @@ -22,11 +22,14 @@ For more information, see this [issue](https://github.com/open-feature/spec/issu

### What is OpenFeature?

[OpenFeature][openfeature-website] is an open standard that provides a vendor-agnostic, community-driven API for feature flagging that works with your favorite feature flag management tool.
[OpenFeature][openfeature-website] is an open standard that provides a vendor-agnostic, community-driven API for feature
flagging that works with your favorite feature flag management tool.

### Why standardize feature flags?

Standardizing feature flags unifies tools and vendors behind a common interface which avoids vendor lock-in at the code level. Additionally, it offers a framework for building extensions and integrations and allows providers to focus on their unique value proposition.
Standardizing feature flags unifies tools and vendors behind a common interface which avoids vendor lock-in at the code
level. Additionally, it offers a framework for building extensions and integrations and allows providers to focus on
their unique value proposition.

## 🔍 Requirements:

Expand Down Expand Up @@ -72,7 +75,8 @@ const boolValue = client.getBooleanValue('boolFlag', false);

### Context-aware evaluation:

Sometimes the value of a flag must take into account some dynamic criteria about the application or user, such as the user location, IP, email address, or the location of the server.
Sometimes the value of a flag must take into account some dynamic criteria about the application or user, such as the
user location, IP, email address, or the location of the server.
In OpenFeature, we refer to this as [`targeting`](https://openfeature.dev/specification/glossary#targeting).
If the flag system you're using supports targeting, you can provide the input data using the `EvaluationContext`.

Expand All @@ -86,15 +90,18 @@ const boolValue = client.getBooleanValue('some-flag', false);

### Providers:

To develop a provider, you need to create a new project and include the OpenFeature SDK as a dependency. This can be a new repository or included in an existing contrib repository available under the OpenFeature organization. Finally, you’ll then need to write the provider itself. In most languages, this can be accomplished by implementing the provider interface exported by the OpenFeature SDK.
To develop a provider, you need to create a new project and include the OpenFeature SDK as a dependency. This can be a
new repository or included in an existing contrib repository available under the OpenFeature organization. Finally,
you’ll then need to write the provider itself. In most languages, this can be accomplished by implementing the provider
interface exported by the OpenFeature SDK.

```typescript
import { JsonValue, Provider, ResolutionDetails } from '@openfeature/web-sdk';

// implement the provider interface
class MyProvider implements Provider {
readonly metadata = {
name: 'My Provider',
name: 'My Provider'
} as const;

resolveBooleanEvaluation(flagKey: string, defaultValue: boolean): ResolutionDetails<boolean> {
Expand All @@ -118,7 +125,9 @@ See [here](https://openfeature.dev/docs/reference/technologies/server/javascript
### Hooks:
Hooks are a mechanism that allow for the addition of arbitrary behavior at well-defined points of the flag evaluation life-cycle. Use cases include validation of the resolved flag value, modifying or adding data to the evaluation context, logging, telemetry, and tracking.
Hooks are a mechanism that allow for the addition of arbitrary behavior at well-defined points of the flag evaluation
life-cycle. Use cases include validation of the resolved flag value, modifying or adding data to the evaluation context,
logging, telemetry, and tracking.
```typescript
import { OpenFeature, Hook, HookContext } from '@openfeature/web-sdk';
Expand All @@ -136,20 +145,24 @@ See [here](https://openfeature.dev/docs/reference/technologies/server/javascript
### Logging:
You can implement the `Logger` interface (compatible with the `console` object, and implementations from common logging libraries such as [winston](https://www.npmjs.com/package/winston)) and set it on the global API object.
You can implement the `Logger` interface (compatible with the `console` object, and implementations from common logging
libraries such as [winston](https://www.npmjs.com/package/winston)) and set it on the global API object.
```typescript
// implement logger
class MyLogger implements Logger {
error(...args: unknown[]): void {
// implement me
}

warn(...args: unknown[]): void {
// implement me
}

info(...args: unknown[]): void {
// implement me
}

debug(...args: unknown[]): void {
// implement me
}
Expand All @@ -159,6 +172,63 @@ class MyLogger implements Logger {
OpenFeature.setLogger(new MyLogger());
```
### Named clients:
You can have several clients, that can be referenced by a name.
Every client can have a different provider assigned. If no provider is assigned to a named client, the global default
provider is used.
```typescript
import { OpenFeature, ProviderEvents } from '@openfeature/web-sdk';

OpenFeature.setProvider(new YourProviderOfChoice())
OpenFeature.setProvider("client-1", new YourOtherProviderOfChoice())

// Uses YourProviderOfChoice (the default)
const unnamedClient = OpenFeature.getClient()

// Uses YourOtherProviderOfChoice as it is set explicitly
const client1 = OpenFeature.getClient("client-1")

// Uses YourProviderOfChoice as no provider is set
const client2 = OpenFeature.getClient("client-2")
```
### Events:
Events provide a way to react to state changes in the provider or underlying flag management system.
You can listen to events of either the OpenFeature API or individual clients.
The events after initialization, `PROVIDER_READY` on success, `PROVIDER_ERROR` on failure during initialization,
are dispatched for every provider.
However, other event types may not be supported by your provider.
Please refer to the documentation of the provider you're using to see what events are supported.
```typescript
import { OpenFeature, ProviderEvents } from '@openfeature/web-sdk';

// OpenFeature API
OpenFeature.addHandler(ProviderEvents.Ready, (eventDetails) => {
console.log(`Ready event from: ${eventDetails.clientName}:`, eventDetails);
});

// Specific client
const client = OpenFeature.getClient();
client.addHandler(ProviderEvents.Error, async (eventDetails) => {
console.log(`Error event from: ${eventDetails.clientName}:`, eventDetails);
});
```
### Shutdown:
The OpenFeature API provides a close function to perform a cleanup of all providers attached to any client.
```typescript
import { OpenFeature, ProviderEvents } from '@openfeature/web-sdk';

await OpenFeature.close()
```
### Complete API documentation:
See [here](https://open-feature.github.io/js-sdk/modules/OpenFeature_Web_SDK.html) for the complete API documentation.
Expand Down
59 changes: 58 additions & 1 deletion packages/server/README.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -11,7 +11,7 @@

[![Project Status: Active – The project has reached a stable, usable state and is being actively developed.](https://www.repostatus.org/badges/latest/active.svg)](https://www.repostatus.org/#active)
[![npm version](https://badge.fury.io/js/@openfeature%2Fjs-sdk.svg)](https://www.npmjs.com/package/@openfeature/js-sdk)
[![Specification](https://img.shields.io/static/v1?label=Specification&message=v0.5.2&color=yellow)](https://github.com/open-feature/spec/tree/v0.5.2)
[![Specification](https://img.shields.io/static/v1?label=Specification&message=v0.6.0&color=yellow)](https://github.com/open-feature/spec/tree/v0.6.0)

## 👋 Hey there! Thanks for checking out the OpenFeature Server SDK

Expand Down Expand Up @@ -161,6 +161,63 @@ class MyLogger implements Logger {
OpenFeature.setLogger(new MyLogger());
```
### Named clients:
You can have several clients, that can be referenced by a name.
Every client can have a different provider assigned. If no provider is assigned to a named client, the global default
provider is used.
```typescript
import { OpenFeature, ProviderEvents } from '@openfeature/web-sdk';

OpenFeature.setProvider(new YourProviderOfChoice())
OpenFeature.setProvider("client-1", new YourOtherProviderOfChoice())

// Uses YourProviderOfChoice (the default)
const unnamedClient = OpenFeature.getClient()

// Uses YourOtherProviderOfChoice as it is set explicitly
const client1 = OpenFeature.getClient("client-1")

// Uses YourProviderOfChoice as no provider is set
const client2 = OpenFeature.getClient("client-2")
```
### Events:
Events provide a way to react to state changes in the provider or underlying flag management system.
You can listen to events of either the OpenFeature API or individual clients.
The events after initialization, `PROVIDER_READY` on success, `PROVIDER_ERROR` on failure during initialization,
are dispatched for every provider.
However, other event types may not be supported by your provider.
Please refer to the documentation of the provider you're using to see what events are supported.
```typescript
import { OpenFeature, ProviderEvents } from '@openfeature/web-sdk';

// OpenFeature API
OpenFeature.addHandler(ProviderEvents.Ready, (eventDetails) => {
console.log(`Ready event from: ${eventDetails.clientName}:`, eventDetails);
});

// Specific client
const client = OpenFeature.getClient();
client.addHandler(ProviderEvents.Error, async (eventDetails) => {
console.log(`Error event from: ${eventDetails.clientName}:`, eventDetails);
});
```
### Shutdown:
The OpenFeature API provides a close function to perform a cleanup of all providers attached to any client.
```typescript
import { OpenFeature, ProviderEvents } from '@openfeature/web-sdk';

await OpenFeature.close()
```
### Complete API documentation:
See [here](https://open-feature.github.io/js-sdk/modules/OpenFeature_JS_SDK.html) for the complete API documentation.
Expand Down

0 comments on commit efa1a0d

Please sign in to comment.