@openfeature/web-sdk 0.3.0-experimental → 0.3.2-experimental

package/README.md

@@ -1,18 +1,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

package/dist/cjs/index.js

@@ -94,22 +94,22 @@ var require_events = __commonJS({
     var NumberIsNaN = Number.isNaN || function NumberIsNaN2(value) {
       return value !== value;
     };
-    function EventEmitter2() {
-      EventEmitter2.init.call(this);
+    function EventEmitter() {
+      EventEmitter.init.call(this);
     }
-    module2.exports = EventEmitter2;
+    module2.exports = EventEmitter;
     module2.exports.once = once;
-    EventEmitter2.EventEmitter = EventEmitter2;
-    EventEmitter2.prototype._events = void 0;
-    EventEmitter2.prototype._eventsCount = 0;
-    EventEmitter2.prototype._maxListeners = void 0;
+    EventEmitter.EventEmitter = EventEmitter;
+    EventEmitter.prototype._events = void 0;
+    EventEmitter.prototype._eventsCount = 0;
+    EventEmitter.prototype._maxListeners = void 0;
     var defaultMaxListeners = 10;
     function checkListener(listener) {
       if (typeof listener !== "function") {
         throw new TypeError('The "listener" argument must be of type Function. Received type ' + typeof listener);
       }
     }
-    Object.defineProperty(EventEmitter2, "defaultMaxListeners", {
+    Object.defineProperty(EventEmitter, "defaultMaxListeners", {
       enumerable: true,
       get: function() {
         return defaultMaxListeners;
@@ -121,14 +121,14 @@ var require_events = __commonJS({
         defaultMaxListeners = arg;
       }
     });
-    EventEmitter2.init = function() {
+    EventEmitter.init = function() {
       if (this._events === void 0 || this._events === Object.getPrototypeOf(this)._events) {
         this._events = /* @__PURE__ */ Object.create(null);
         this._eventsCount = 0;
       }
       this._maxListeners = this._maxListeners || void 0;
     };
-    EventEmitter2.prototype.setMaxListeners = function setMaxListeners(n) {
+    EventEmitter.prototype.setMaxListeners = function setMaxListeners(n) {
       if (typeof n !== "number" || n < 0 || NumberIsNaN(n)) {
         throw new RangeError('The value of "n" is out of range. It must be a non-negative number. Received ' + n + ".");
       }
@@ -137,13 +137,13 @@ var require_events = __commonJS({
     };
     function _getMaxListeners(that) {
       if (that._maxListeners === void 0)
-        return EventEmitter2.defaultMaxListeners;
+        return EventEmitter.defaultMaxListeners;
       return that._maxListeners;
     }
-    EventEmitter2.prototype.getMaxListeners = function getMaxListeners() {
+    EventEmitter.prototype.getMaxListeners = function getMaxListeners() {
       return _getMaxListeners(this);
     };
-    EventEmitter2.prototype.emit = function emit(type) {
+    EventEmitter.prototype.emit = function emit(type) {
       var args = [];
       for (var i = 1; i < arguments.length; i++)
         args.push(arguments[i]);
@@ -221,11 +221,11 @@ var require_events = __commonJS({
       }
       return target;
     }
-    EventEmitter2.prototype.addListener = function addListener(type, listener) {
+    EventEmitter.prototype.addListener = function addListener(type, listener) {
       return _addListener(this, type, listener, false);
     };
-    EventEmitter2.prototype.on = EventEmitter2.prototype.addListener;
-    EventEmitter2.prototype.prependListener = function prependListener(type, listener) {
+    EventEmitter.prototype.on = EventEmitter.prototype.addListener;
+    EventEmitter.prototype.prependListener = function prependListener(type, listener) {
       return _addListener(this, type, listener, true);
     };
     function onceWrapper() {
@@ -244,17 +244,17 @@ var require_events = __commonJS({
       state.wrapFn = wrapped;
       return wrapped;
     }
-    EventEmitter2.prototype.once = function once2(type, listener) {
+    EventEmitter.prototype.once = function once2(type, listener) {
       checkListener(listener);
       this.on(type, _onceWrap(this, type, listener));
       return this;
     };
-    EventEmitter2.prototype.prependOnceListener = function prependOnceListener(type, listener) {
+    EventEmitter.prototype.prependOnceListener = function prependOnceListener(type, listener) {
       checkListener(listener);
       this.prependListener(type, _onceWrap(this, type, listener));
       return this;
     };
-    EventEmitter2.prototype.removeListener = function removeListener(type, listener) {
+    EventEmitter.prototype.removeListener = function removeListener(type, listener) {
       var list, events, position, i, originalListener;
       checkListener(listener);
       events = this._events;
@@ -294,8 +294,8 @@ var require_events = __commonJS({
       }
       return this;
     };
-    EventEmitter2.prototype.off = EventEmitter2.prototype.removeListener;
-    EventEmitter2.prototype.removeAllListeners = function removeAllListeners(type) {
+    EventEmitter.prototype.off = EventEmitter.prototype.removeListener;
+    EventEmitter.prototype.removeAllListeners = function removeAllListeners(type) {
       var listeners, events, i;
       events = this._events;
       if (events === void 0)
@@ -347,20 +347,20 @@ var require_events = __commonJS({
         return unwrap ? [evlistener.listener || evlistener] : [evlistener];
       return unwrap ? unwrapListeners(evlistener) : arrayClone(evlistener, evlistener.length);
     }
-    EventEmitter2.prototype.listeners = function listeners(type) {
+    EventEmitter.prototype.listeners = function listeners(type) {
       return _listeners(this, type, true);
     };
-    EventEmitter2.prototype.rawListeners = function rawListeners(type) {
+    EventEmitter.prototype.rawListeners = function rawListeners(type) {
       return _listeners(this, type, false);
     };
-    EventEmitter2.listenerCount = function(emitter, type) {
+    EventEmitter.listenerCount = function(emitter, type) {
       if (typeof emitter.listenerCount === "function") {
         return emitter.listenerCount(type);
       } else {
         return listenerCount.call(emitter, type);
       }
     };
-    EventEmitter2.prototype.listenerCount = listenerCount;
+    EventEmitter.prototype.listenerCount = listenerCount;
     function listenerCount(type) {
       var events = this._events;
       if (events !== void 0) {
@@ -373,7 +373,7 @@ var require_events = __commonJS({
       }
       return 0;
     }
-    EventEmitter2.prototype.eventNames = function eventNames() {
+    EventEmitter.prototype.eventNames = function eventNames() {
       return this._eventsCount > 0 ? ReflectOwnKeys(this._events) : [];
     };
     function arrayClone(arr, n) {
@@ -464,20 +464,8 @@ __export(src_exports, {
   TypeMismatchError: () => TypeMismatchError
 });
 module.exports = __toCommonJS(src_exports);
-var import_events = __toESM(require_events());
 
 // ../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 = {
   /**
    * The resolved value was the result of a dynamic evaluation, such as a rule or specific user-targeting.
@@ -721,6 +709,20 @@ var NoopFeatureProvider = class {
 };
 var NOOP_PROVIDER = new NoopFeatureProvider();
 
+// src/types.ts
+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 || {});
+
 // src/open-feature.ts
 var GLOBAL_OPENFEATURE_API_KEY = Symbol.for("@openfeature/js.api");
 var _globalThis = globalThis;
@@ -815,7 +817,7 @@ var OpenFeatureAPI = class extends OpenFeatureCommonAPI {
   getClient(name, version) {
     return new OpenFeatureClient(
       // 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,
       () => this._providerReady,
       () => this._apiEvents,