fix: provider js-doc improvments (#506)

In 3 event provider implementations,
[flagd-java](open-feature/java-sdk-contrib#361 (review)),
[go-feature-flag-web](open-feature/js-sdk-contrib#474 (comment)),
and even my own implementation of flagd-js, authors have forgotten to
properly implement `getState` (which means the SDK assumes the provider
is already `READY` and doesn't run `initialize()`.)

This is an easy pitfall. To help with this, I'm adding doc.

We may be able to improve the interfaces to help with this, but I think
this is a safe and helpful change for now.

Relates to: open-feature/java-sdk#531

Signed-off-by: Todd Baert <[email protected]>

Author: toddbaert

packages/shared/src/provider/provider.ts

@@ -2,18 +2,44 @@ import { OpenFeatureEventEmitter } from '../events';
 import { Metadata } from '../types';
 import { EvaluationContext } from '../evaluation';
 
+/**
+ * The state of the provider.
+ */
 export enum ProviderStatus {
+  /**
+   * The provider has not been initialized and cannot yet evaluate flags.
+   */
   NOT_READY = 'NOT_READY',
+
+  /**
+   * The provider is ready to resolve flags.
+   */
   READY = 'READY',
+
+  /**
+   * The provider is in an error state and unable to evaluate flags.
+   */
   ERROR = 'ERROR',
 }
 
+/**
+ * Static data about the provider.
+ */
 export interface ProviderMetadata extends Metadata {
   readonly name: string;
 }
 
 export interface CommonProvider {
   readonly metadata: ProviderMetadata;
+
+  /**
+   * Returns a representation of the current readiness of the provider.
+   * If the provider needs to be initialized, it should return {@link ProviderStatus.READY}.
+   * If the provider is in an error state, it should return {@link ProviderStatus.ERROR}.
+   * If the provider is functioning normally, it should return {@link ProviderStatus.NOT_READY}.
+   * 
+   * _Providers which do not implement this method are assumed to be ready immediately._
+   */
   readonly status?: ProviderStatus;
 
   /**
@@ -22,15 +48,19 @@ export interface CommonProvider {
    */
   events?: OpenFeatureEventEmitter;
 
+  /**
+   * A function used to shut down the provider.
+   * Called when this provider is replaced with a new one, or when the OpenFeature is shut down.
+   */
   onClose?(): Promise<void>;
 
   /**
-   * A handler function used to setup the provider.
-   * Called by the SDK after the provider is set.
+   * A function used to setup the provider.
+   * Called by the SDK after the provider is set if the provider's status is {@link ProviderStatus.NOT_READY}.
    * When the returned promise resolves, the SDK fires the ProviderEvents.Ready event.
    * If the returned promise rejects, the SDK fires the ProviderEvents.Error event.
    * Use this function to perform any context-dependent setup within the provider.
    * @param context
    */
   initialize?(context?: EvaluationContext): Promise<void>;
-}
+}