reference-docs
Classes
Type Aliases
ActiveVariant
Ƭ ActiveVariant: Object
This represents an active experiment variant within Causal. This is intended for reporting information to other systems. It should not be used as an input for any display or logic on your site.
Active variants are available on the Session.activeVariants property and the CausalOptions.onImpression callback
Type declaration
| Name | Type | Description |
|---|---|---|
experimentId | string | the id of the experiment |
experimentName | string | the name of the experiment |
variantId | string | undefined | the name of the variant, undefined for control |
variantName | string | the name of the variant |
CausalOptions
Ƭ CausalOptions: Object
Causal configuration options that can be passed to initCausal
Type declaration
| Name | Type | Description |
|---|---|---|
baseUrl? | string | By default Causal will send all network requests as defined by the impression server environment variables. See: https://tech.causallabs.io/docs/reference/install/configuration/ You can alternatively set it here. |
logIServerCommErrors? | boolean | If true, log to warn() any errors communicating with the iserver. Errors include timeouts, exceptions thrown from fetch, and empty responses. The default is true. |
logIServerDetails? | boolean | If true, log to info() all the request and response information to/from the iserver. This is useful for diagnostics, and generally should NOT be set. It is very verbose. The default is false. |
logLevel? | ("info" | "warn" | "error")[] | What should be logged The default it to log everything To suppress all logging pass in an empty array |
onImpression? | (info: { allFeatures: RequestedFeature[] ; allVariants: ActiveVariant[] ; newFeatures: RequestedFeature[] ; newVariants: ActiveVariant[] }) => void | Callback called when an impression is returned. This is intended for reporting information to other systems. It should not be used as an input for any display or logic on your site. |
onUpdateActiveVariants? | (variants: ActiveVariant[]) => void | Deprecated Callback called whenever the active variants are updated. This is intended for reporting information to other systems. It should not be used as an input for any display or logic on your site. |
timeoutMs? | number | How long to wait for the impression server to respond before a timeout. The default is 1000 ms (1 second) |
CommSnapshot
Ƭ CommSnapshot: Object
Information relating to the communication with the impression server
Type declaration
| Name | Type |
|---|---|
errorsAndWarnings | ErrorTypes[] |
errorsReceived | number |
featuresReceived | number |
featuresRequested | number |
fetches | number |
ErrorFetch
Ƭ ErrorFetch: Object
ErrorType indicated that a network fetch failed in some way
Type declaration
| Name | Type |
|---|---|
errorType | "fetch" |
message | string |
ErrorFetchResponse
Ƭ ErrorFetchResponse: Object
Error type indicated the response data was invalid in some way
Type declaration
| Name | Type |
|---|---|
errorType | "fetchResponse" |
message | string |
ErrorField
Ƭ ErrorField: Object
Error type indicating a field level error occurred
Type declaration
| Name | Type |
|---|---|
errorType | "field" |
fieldErrors | Partial<Record<FeatureNames, string>> |
message | string |
ErrorTypes
Ƭ ErrorTypes: ErrorFetch | ErrorFetchResponse | ErrorUnknown | ErrorField
Union type of possible Causal error types
ErrorUnknown
Ƭ ErrorUnknown: Object
Error type indicating an unknown error occurred
Type declaration
| Name | Type |
|---|---|
errorType | "unknown" |
message | string |
ImpressionJSON
Ƭ ImpressionJSON: Object
JSON format for an impression.
This can be safely serialized to JSON with functions like JSON.stringify().
Use the function toImpression to convert back to an impression.
RequestedFeature
Ƭ RequestedFeature: Object
This represents the state of all features requested so far. This is intended for reporting information to other systems. It should not be used as an input for any display or logic on your site.
RequestedFeature is on the Session.requestedFeatures property and the CausalOptions.onImpression callback
Type declaration
| Name | Type |
|---|---|
featureName | string |
isOn | boolean |
SelectFeatures
Ƭ SelectFeatures<T>: T
This is a utility type so autocomplete works better.
I.e. type MyFeatures = SelectFeatures<"this_will_autocomplete">.
If it is not autocompleting, try typing a quote (') or double quote (").
Type parameters
| Name | Type |
|---|---|
T | extends FeatureNames |
SessionArgs
Ƭ SessionArgs: Object
The arguments defined in the args section of the FDL schema
Type declaration
| Name | Type |
|---|---|
deviceId | string |
SessionJSON
Ƭ SessionJSON: Object
A session converted to JSON. Used in conjunction with Session.toJSON and Session.fromJSON. These are useful to transfer a session across a JSON serialization boundary
Type declaration
| Name | Type |
|---|---|
activeVariants | ActiveVariant[] |
cacheJson | Record<string, unknown> |
commSnapshotJson | CommSnapshot |
featureJson | _RequestStoreEntry & { args: unknown ; featureName: string }[] | undefined |
originator | "ssr" | "csr" |
sessionArgs | Partial<SessionArgs> |
Variables
SessionContext
• Const SessionContext: Context<undefined | Session>
A React context to hold a Session This uses the standard React context provider pattern
allFeatureTypes
• Const allFeatureTypes: Object
Deprecated
Type declaration
| Name | Type |
|---|---|
ExampleFeature | typeof ExampleFeature |
ExampleFeature2 | typeof ExampleFeature2 |
defaultFlags
• Const defaultFlags: Flags<FeatureNames>
The state of the feature flags when the FDL was compiled to this file.
Functions
createQuery
▸ createQuery<T>(args): Query<T>
Create a query to use with requestImpression or useImpression.
Typeparam
The names of the features to query for.
Type parameters
| Name | Type |
|---|---|
T | extends "ExampleFeature" | "ExampleFeature2" |
Parameters
| Name | Type | Description |
|---|---|---|
args | QueryArgs<T> | The arguments for each feature in T. |
Returns
Query<T>
Query to use with requestImpression or useImpression.
initCausal
▸ initCausal(options?, debugOptions?): void
An optional method to set Causal options
Parameters
| Name | Type | Description |
|---|---|---|
options? | CausalOptions | Configurable options. |
debugOptions? | CausalDebugOptions | Options that may change between releases |
Returns
void
isFeatureType
▸ isFeatureType<F, T>(feature, toTestType): feature is Exclude<Impression<"ExampleFeature" | "ExampleFeature2">[T], undefined> & Object & F
Type predicate to narrows the type of a feature. Useful for narrowing union types. Example: const feature: FeatureA | FeatureB = ... if (isImpression(impression, "FeatureA")) { featureA // feature has been narrowed to type FeatureA }
Type parameters
| Name | Type |
|---|---|
F | extends Feature<"ExampleFeature" | "ExampleFeature2"> |
T | extends "ExampleFeature" | "ExampleFeature2" |
Parameters
| Name | Type |
|---|---|
feature | undefined | F |
toTestType | T |
Returns
feature is Exclude<Impression<"ExampleFeature" | "ExampleFeature2">[T], undefined> & Object & F
isImpressionType
▸ isImpressionType<I, T>(impression, toTestType): impression is { [P in "ExampleFeature" | "ExampleFeature2" | "toJSON" | "sessionKeys"]: ImpressionImpl[P] } & SessionEvents & I
Type predicate to narrows the type of an impression. Useful for narrowing union types. Example: const impression: Impression<A> | Impression<B> = ... if (isImpression(impression, "A")) { impression.A // impression has been narrowed to type A }
Type parameters
| Name | Type |
|---|---|
I | extends { ExampleFeature: undefined | ExampleFeature ; ExampleFeature2: undefined | ExampleFeature2 ; sessionKeys: Partial<{ deviceId: undefined | string = s.deviceId }> ; toJSON: () => ImpressionJSON } & SessionEvents<I> |
T | extends "ExampleFeature" | "ExampleFeature2" |
Parameters
| Name | Type |
|---|---|
impression | I |
toTestType | T |
Returns
impression is { [P in "ExampleFeature" | "ExampleFeature2" | "toJSON" | "sessionKeys"]: ImpressionImpl[P] } & SessionEvents & I
qb
▸ qb(): Query<never>
Create a query to use with requestImpression or useImpression using the builder pattern. This is the same as QueryBuilder, just less typing
Returns
Query<never>
Query to use with requestImpression or useImpression.
queryBuilder
▸ queryBuilder(): Query<never>
Create a query to use with requestImpression or useImpression using the builder pattern.
Returns
Query<never>
Query to use with requestImpression or useImpression.
toImpression
▸ toImpression<T>(impressionJson): ImpressionType<Query<T>>
Convert a ImpressionJSON back to an impression.
Type parameters
| Name | Type |
|---|---|
T | extends "ExampleFeature" | "ExampleFeature2" |
Parameters
| Name | Type |
|---|---|
impressionJson | ImpressionJSON |
Returns
ImpressionType<Query<T>>
toImpressionImpl
▸ toImpressionImpl(__namedParameters): ImpressionImpl
Parameters
| Name | Type |
|---|---|
__namedParameters | ImpressionJSON |
Returns
ImpressionImpl
useFeature
▸ useFeature<T>(featureReq, impressionId?, session?): DistributeFeature<Feature<T>> | undefined
React hook to get a single feature. As compared to useImpression this only retrieves a single feature. If the request is loading it will returned undefined. It does NOT return an error state, so you need to be happy with the control values on error.
Type parameters
| Name | Type |
|---|---|
T | extends never |
Parameters
| Name | Type |
|---|---|
featureReq | undefined | T |
impressionId? | string |
session? | Session |
Returns
DistributeFeature<Feature<T>> | undefined
▸ useFeature<T>(featureReq, impressionId?, session?): DistributeFeature<Feature<T>> | undefined
React hook to get a single feature. As compared to useImpression this only retrieves a single feature. If the request is loading it will returned undefined. It does NOT return an error state, so you need to be happy with the control values on error.
Type parameters
| Name | Type |
|---|---|
T | extends "ExampleFeature" | "ExampleFeature2" |
Parameters
| Name | Type |
|---|---|
featureReq | undefined | Query<T> |
impressionId? | string |
session? | Session |
Returns
DistributeFeature<Feature<T>> | undefined
useImpression
▸ useImpression<Q>(query, impressionId?, session?): Object
React hook to get both the impression and the on/off flags associated with a feature
Type parameters
| Name | Type |
|---|---|
Q | extends Query<"ExampleFeature" | "ExampleFeature2", Q> |
Parameters
| Name | Type |
|---|---|
query | undefined | Q |
impressionId? | string |
session? | Session |
Returns
Object
| Name | Type |
|---|---|
error? | ErrorTypes |
flags | FlagsType<Q> | undefined |
impression | Q extends Query<infer T> ? Impression<T> : never |
loading | boolean |
useSession
▸ useSession(): Session | undefined
A React hook to get the current Session in the SessionContext
Returns
Session | undefined
useSessionJSON
▸ useSessionJSON(json): Session
Creates a session from transferred SessionJSON originally created with Session.toJSON. This function is preferred to Session.fromJSON, as this function ensures react client hydration works correctly
Parameters
| Name | Type |
|---|---|
json | SessionJSON |