@openfeature/web-sdk - npm Package Compare versions

Comparing version 0.3.1-experimental to 0.3.2-experimental

dist/cjs/index.js

@@ -469,13 +469,2 @@ "use strict";
 // ../shared/src/types.ts
-var ProviderEvents = /* @__PURE__ */ ((ProviderEvents2) => {
-  ProviderEvents2["Ready"] = "PROVIDER_READY";
-  ProviderEvents2["Error"] = "PROVIDER_ERROR";
-  ProviderEvents2["ConfigurationChanged"] = "PROVIDER_CONFIGURATION_CHANGED";
-  ProviderEvents2["Shutdown"] = "PROVIDER_SHUTDOWN";
-  return ProviderEvents2;
-})(ProviderEvents || {});
-var ApiEvents = /* @__PURE__ */ ((ApiEvents2) => {
-  ApiEvents2["ProviderChanged"] = "providerChanged";
-  return ApiEvents2;
-})(ApiEvents || {});
 var StandardResolutionReasons = {
@@ -726,2 +715,13 @@ /**
 var import_events = __toESM(require_events());
+var ProviderEvents = /* @__PURE__ */ ((ProviderEvents2) => {
+  ProviderEvents2["Ready"] = "PROVIDER_READY";
+  ProviderEvents2["Error"] = "PROVIDER_ERROR";
+  ProviderEvents2["ConfigurationChanged"] = "PROVIDER_CONFIGURATION_CHANGED";
+  ProviderEvents2["Stale"] = "PROVIDER_STALE";
+  return ProviderEvents2;
+})(ProviderEvents || {});
+var ApiEvents = /* @__PURE__ */ ((ApiEvents2) => {
+  ApiEvents2["ProviderChanged"] = "providerChanged";
+  return ApiEvents2;
+})(ApiEvents || {});
 
@@ -822,3 +822,3 @@ // src/open-feature.ts
       // functions are passed here to make sure that these values are always up to date,
-      // and so we don't have to make these public properties on the API class. 
+      // and so we don't have to make these public properties on the API class.
       () => this._provider,
@@ -825,0 +825,0 @@ () => this._providerReady,

dist/esm/index.js

@@ -437,13 +437,2 @@ var __create = Object.create;
 // ../shared/src/types.ts
-var ProviderEvents = /* @__PURE__ */ ((ProviderEvents2) => {
-  ProviderEvents2["Ready"] = "PROVIDER_READY";
-  ProviderEvents2["Error"] = "PROVIDER_ERROR";
-  ProviderEvents2["ConfigurationChanged"] = "PROVIDER_CONFIGURATION_CHANGED";
-  ProviderEvents2["Shutdown"] = "PROVIDER_SHUTDOWN";
-  return ProviderEvents2;
-})(ProviderEvents || {});
-var ApiEvents = /* @__PURE__ */ ((ApiEvents2) => {
-  ApiEvents2["ProviderChanged"] = "providerChanged";
-  return ApiEvents2;
-})(ApiEvents || {});
 var StandardResolutionReasons = {
@@ -694,2 +683,13 @@ /**
 var import_events = __toESM(require_events());
+var ProviderEvents = /* @__PURE__ */ ((ProviderEvents2) => {
+  ProviderEvents2["Ready"] = "PROVIDER_READY";
+  ProviderEvents2["Error"] = "PROVIDER_ERROR";
+  ProviderEvents2["ConfigurationChanged"] = "PROVIDER_CONFIGURATION_CHANGED";
+  ProviderEvents2["Stale"] = "PROVIDER_STALE";
+  return ProviderEvents2;
+})(ProviderEvents || {});
+var ApiEvents = /* @__PURE__ */ ((ApiEvents2) => {
+  ApiEvents2["ProviderChanged"] = "providerChanged";
+  return ApiEvents2;
+})(ApiEvents || {});
 
@@ -790,3 +790,3 @@ // src/open-feature.ts
       // functions are passed here to make sure that these values are always up to date,
-      // and so we don't have to make these public properties on the API class. 
+      // and so we don't have to make these public properties on the API class.
       () => this._provider,
@@ -793,0 +793,0 @@ () => this._providerReady,

dist/types.d.ts

 type PrimitiveValue = null | boolean | string | number;
-declare enum ProviderEvents {
-    /**
-     * The provider is ready to evaluate flags.
-     */
-    Ready = "PROVIDER_READY",
-    /**
-     * The provider is in an error state.
-     */
-    Error = "PROVIDER_ERROR",
-    /**
-     * The flag configuration in the source-of-truth has changed.
-     */
-    ConfigurationChanged = "PROVIDER_CONFIGURATION_CHANGED",
-    /**
-     * The provider is transitioning to a state of unavailability.
-     */
-    Shutdown = "PROVIDER_SHUTDOWN"
-}
-interface EventData {
-    flagKeysChanged?: string[];
-    changeMetadata?: {
-        [key: string]: boolean | string;
-    };
-}
-declare enum ApiEvents {
-    ProviderChanged = "providerChanged"
-}
-interface Eventing {
-    addHandler(notificationType: string, handler: Handler): void;
-}
-type EventContext = {
-    notificationType: string;
-    [key: string]: unknown;
-};
-type Handler = (eventContext?: EventContext) => void;
-type EventCallbackMessage = (eventContext: EventContext) => void;
 type JsonObject = {
@@ -351,2 +315,38 @@ [key: string]: JsonValue;
 
+declare enum ProviderEvents {
+    /**
+     * The provider is ready to evaluate flags.
+     */
+    Ready = "PROVIDER_READY",
+    /**
+     * The provider is in an error state.
+     */
+    Error = "PROVIDER_ERROR",
+    /**
+     * The flag configuration in the source-of-truth has changed.
+     */
+    ConfigurationChanged = "PROVIDER_CONFIGURATION_CHANGED",
+    /**
+     * The provider's cached state is not longer valid and may not be up-to-date with the source of truth.
+     */
+    Stale = "PROVIDER_STALE"
+}
+interface EventData {
+    flagKeysChanged?: string[];
+    changeMetadata?: {
+        [key: string]: boolean | string;
+    };
+}
+declare enum ApiEvents {
+    ProviderChanged = "providerChanged"
+}
+interface Eventing {
+    addHandler(notificationType: string, handler: Handler): void;
+}
+type EventContext = {
+    notificationType: string;
+    [key: string]: unknown;
+};
+type Handler = (eventContext?: EventContext) => void;
+type EventCallbackMessage = (eventContext: EventContext) => void;
 /**
@@ -353,0 +353,0 @@ * Interface that providers must implement to resolve flag values for their particular

package.json

 {
   "name": "@openfeature/web-sdk",
-  "version": "0.3.1-experimental",
+  "version": "0.3.2-experimental",
   "description": "OpenFeature SDK for Web",
@@ -49,3 +49,3 @@ "main": "./dist/cjs/index.js",
   "devDependencies": {
-    "@openfeature/shared": "0.0.2"
+    "@openfeature/shared": "0.0.3"
   },
@@ -52,0 +52,0 @@ "typedoc": {

README.md

@@ -1,18 +0,166 @@
-# @openfeature/web-sdk
+<!-- markdownlint-disable MD033 -->
+<p align="center">
+  <picture>
+    <source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/open-feature/community/0e23508c163a6a1ac8c0ced3e4bd78faafe627c7/assets/logo/horizontal/white/openfeature-horizontal-white.svg">
+    <source media="(prefers-color-scheme: light)" srcset="https://raw.githubusercontent.com/open-feature/community/0e23508c163a6a1ac8c0ced3e4bd78faafe627c7/assets/logo/horizontal/black/openfeature-horizontal-black.svg">
+    <img align="center" alt="OpenFeature Logo">
+  </picture>
+</p>
 
-Experimental web implementation of OpenFeature intended for use in web-browsers.
-  
-## Installation
+<h2 align="center">OpenFeature Web SDK</h2>
 
-```shell
+[![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)
+
+## 🧪 This SDK is experimental
+
+The Web SDK is under development and based on a experimental client concepts.
+For more information, see this [issue](https://github.com/open-feature/spec/issues/167).
+
+## 👋 Hey there! Thanks for checking out the OpenFeature Web SDK
+
+### 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.
+
+### 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.
+
+## 🔍 Requirements:
+
+- ES2015-compatible web browser (Chrome, Edge, Firefox, etc)
+
+## 📦 Installation:
+
+### npm
+
+```sh
 npm install @openfeature/web-sdk
 ```
 
-or
+### yarn
 
-```shell
+```sh
 yarn add @openfeature/web-sdk
 ```
 
-## Usage
-Coming soon!
+## 🌟 Features:
+
+- support for various [providers](https://openfeature.dev/docs/reference/concepts/provider)
+- easy integration and extension via [hooks](https://openfeature.dev/docs/reference/concepts/hooks)
+- handle flags of any type: bool, string, numeric and object
+- [context-aware](https://openfeature.dev/docs/reference/concepts/evaluation-context) evaluation
+
+## 🚀 Usage:
+
+### Basics:
+
+```typescript
+import { OpenFeature } from '@openfeature/web-sdk';
+
+// configure a provider
+await OpenFeature.setProvider(new YourProviderOfChoice());
+
+// create a client
+const client = OpenFeature.getClient('my-app');
+
+// get a bool flag value
+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.
+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`.
+
+```typescript
+// global context for static data
+await OpenFeature.setContext({ origin: document.location.host })
+
+// use contextual data to determine a flag value
+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.
+
+```typescript
+import { JsonValue, Provider, ResolutionDetails } from '@openfeature/web-sdk';
+
+// implement the provider interface
+class MyProvider implements Provider {
+  readonly metadata = {
+    name: 'My Provider',
+  } as const;
+
+  resolveBooleanEvaluation(flagKey: string, defaultValue: boolean): ResolutionDetails<boolean> {
+    // resolve a boolean flag value
+  }
+
+  resolveStringEvaluation(flagKey: string, defaultValue: string): ResolutionDetails<string> {
+    // resolve a string flag value
+  }
+
+  resolveNumberEvaluation(flagKey: string, defaultValue: number): ResolutionDetails<number> {
+    // resolve a numeric flag value
+  }
+
+  resolveObjectEvaluation<T extends JsonValue>(flagKey: string, defaultValue: T): ResolutionDetails<T> {
+    // resolve an object flag value
+  }
+```
+
+See [here](https://openfeature.dev/docs/reference/technologies/server/javascript) for a catalog of available providers.
+
+### 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.
+
+```typescript
+import { OpenFeature, Hook, HookContext } from '@openfeature/web-sdk';
+
+// Example hook that logs if an error occurs during flag evaluation
+export class GlobalDebugHook implements Hook {
+  after(hookContext: HookContext, err: Error) {
+    console.log('hook context', hookContext);
+    console.error(err);
+  }
+}
+```
+
+See [here](https://openfeature.dev/docs/reference/technologies/server/javascript) for a catalog of available hooks.
+
+### 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.
+
+```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
+  }
+}
+
+// set the logger
+OpenFeature.setLogger(new MyLogger());
+```
+
+### Complete API documentation:
+
+See [here](https://open-feature.github.io/js-sdk/modules/OpenFeature_Web_SDK.html) for the complete API documentation.
+
+[openfeature-website]: https://openfeature.dev

No alert changes

Improved metrics

Total package byte prevSize

269138

increased by2.38%

Number of lines in readme file

167

increased by778.95%

No dependency changes