Skip to main content

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

NameTypeDescription
experimentIdstringthe id of the experiment
experimentNamestringthe name of the experiment
variantIdstring | undefinedthe name of the variant, undefined for control
variantNamestringthe name of the variant

CausalOptions

Ƭ CausalOptions: Object

Causal configuration options that can be passed to initCausal

Type declaration

NameTypeDescription
baseUrl?stringBy 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?booleanIf 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?booleanIf 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[] }) => voidCallback 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[]) => voidDeprecated 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?numberHow 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

NameType
errorsAndWarningsErrorTypes[]
errorsReceivednumber
featuresReceivednumber
featuresRequestednumber
fetchesnumber

ErrorFetch

Ƭ ErrorFetch: Object

ErrorType indicated that a network fetch failed in some way

Type declaration

NameType
errorType"fetch"
messagestring

ErrorFetchResponse

Ƭ ErrorFetchResponse: Object

Error type indicated the response data was invalid in some way

Type declaration

NameType
errorType"fetchResponse"
messagestring

ErrorField

Ƭ ErrorField: Object

Error type indicating a field level error occurred

Type declaration

NameType
errorType"field"
fieldErrorsPartial<Record<FeatureNames, string>>
messagestring

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

NameType
errorType"unknown"
messagestring

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

NameType
featureNamestring
isOnboolean

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

NameType
Textends FeatureNames

SessionArgs

Ƭ SessionArgs: Object

The arguments defined in the args section of the FDL schema

Type declaration

NameType
deviceIdstring

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

NameType
activeVariantsActiveVariant[]
cacheJsonRecord<string, unknown>
commSnapshotJsonCommSnapshot
featureJson_RequestStoreEntry & { args: unknown ; featureName: string }[] | undefined
originator"ssr" | "csr"
sessionArgsPartial<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

NameType
ExampleFeaturetypeof ExampleFeature
ExampleFeature2typeof 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

NameType
Textends "ExampleFeature" | "ExampleFeature2"

Parameters

NameTypeDescription
argsQueryArgs<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

NameTypeDescription
options?CausalOptionsConfigurable options.
debugOptions?CausalDebugOptionsOptions 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

NameType
Fextends Feature<"ExampleFeature" | "ExampleFeature2">
Textends "ExampleFeature" | "ExampleFeature2"

Parameters

NameType
featureundefined | F
toTestTypeT

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

NameType
Iextends { ExampleFeature: undefined | ExampleFeature ; ExampleFeature2: undefined | ExampleFeature2 ; sessionKeys: Partial<{ deviceId: undefined | string = s.deviceId }> ; toJSON: () => ImpressionJSON } & SessionEvents<I>
Textends "ExampleFeature" | "ExampleFeature2"

Parameters

NameType
impressionI
toTestTypeT

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

NameType
Textends "ExampleFeature" | "ExampleFeature2"

Parameters

NameType
impressionJsonImpressionJSON

Returns

ImpressionType<Query<T>>


toImpressionImpl

toImpressionImpl(__namedParameters): ImpressionImpl

Parameters

NameType
__namedParametersImpressionJSON

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

NameType
Textends never

Parameters

NameType
featureRequndefined | 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

NameType
Textends "ExampleFeature" | "ExampleFeature2"

Parameters

NameType
featureRequndefined | 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

NameType
Qextends Query<"ExampleFeature" | "ExampleFeature2", Q>

Parameters

NameType
queryundefined | Q
impressionId?string
session?Session

Returns

Object

NameType
error?ErrorTypes
flagsFlagsType<Q> | undefined
impressionQ extends Query<infer T> ? Impression<T> : never
loadingboolean

useSession

useSession(): Session | undefined

A React hook to get the current Session in the SessionContext

Returns

Session | undefined

Session


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

NameType
jsonSessionJSON

Returns

Session