reference-docs
Classes
Interfaces
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. |
defaultPageType? | "SSR" | "SSG" | "CSR" | The default page type for your site. SSR: Server side rendered CSR: Client side rendered SSG: Static site generation This impact the default render strategy used by Causal. The default is "SSG". If you know your site is SSR or CSR, you can set this to optimize performance. You can change this on a per page basis by using OptionsContext Please visit https://tech.causallabs.io/docs/howto/hydration for more details |
logIServerCommErrors? | boolean | Deprecated If true, log to error() 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 |
DistributeFeature
Ƭ DistributeFeature<F>: F extends Feature<infer T> ? T extends unknown ? Feature<T> : never : never
Converts Feature<A|B|C> into Feature<A> | Feature<B> | Feature<C>
Type parameters
| Name |
|---|
F |
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 |
Feature
Ƭ Feature<T>: Exclude<Impression<FeatureNames>[T], undefined> & { featureName: T ; impression: Impression<T> ; impressionId: string }
Type parameters
| Name | Type |
|---|---|
T | extends FeatureNames |
FeatureNames
Ƭ FeatureNames: keyof typeof allFeatureTypes
FeatureNamesNoArgs
Ƭ FeatureNamesNoArgs: keyof OmitNever<{ [F in FeatureNames]: Parameters<Query<F>[`get${F}`]>[0] extends undefined ? F : never }>
Flags
Ƭ Flags<T>: { [P in T]: boolean }
Type parameters
| Name | Type |
|---|---|
T | extends FeatureNames |
FlagsType
Ƭ FlagsType<Q>: Q extends Query<infer T> ? Flags<T> : never
Type parameters
| Name |
|---|
Q |
Impression
Ƭ Impression<T>: { [P in keyof Pick<_ImpressionImpl, T | "toJSON" | "sessionKeys">]: _ImpressionImpl[P] } & SessionEvents
Type parameters
| Name | Type |
|---|---|
T | extends FeatureNames |
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.
ImpressionType
Ƭ ImpressionType<Q>: Q extends Query<infer T> ? Impression<T> : never
Type parameters
| Name |
|---|
Q |
QueryArgs
Ƭ QueryArgs<T>: { [F in T]: Parameters<Query<T>[`get${F}`]>[number] | Record<string, never> }
Represents the type of a query, both its features and arguments.
This type generally will not be constructed manually, but instead be inferred from the return value of queryBuilder or createQuery.
Paramtype
The feature to query for
Type parameters
| Name | Type |
|---|---|
T | extends FeatureNames |
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 useSessionJSON to transfer a session for SSR
Type declaration
| Name | Type |
|---|---|
activeVariants | ActiveVariant[] |
cacheJson | Record<string, unknown> |
commSnapshotJson | CommSnapshot |
featureJson | _RequestStoreEntry & { featureName: string ; strArgs: string }[] | undefined |
originator | "ssr" | "csr" |
sessionArgs | Partial<SessionArgs> |
Variables
OptionContext
• Const OptionContext: Context<undefined | Pick<CausalOptions, "defaultPageType">>
A React context to hold Causal options that you want to change from the defaults This uses the standard React context provider pattern
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 | "OFF" | 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.
sessionKeys
▸ sessionKeys(s): Object
Parameters
| Name | Type |
|---|---|
s | Partial<SessionArgs> |
Returns
Object
| Name | Type |
|---|---|
deviceId | undefined | string |
signalInstance
▸ signalInstance(feature, event, args): void
Parameters
| Name | Type |
|---|---|
feature | FeatureBase |
event | string |
args | unknown |
Returns
void
sortReplacer
▸ sortReplacer(_, value): any
Parameters
| Name | Type |
|---|---|
_ | any |
value | any |
Returns
any
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>>
useFeature
▸ useFeature<T>(featureReq, impressionId?, session?): DistributeFeature<Feature<T>> | undefined | "OFF"
React hook to get a single feature.
As compared to useImpression this only retrieves a single feature.
If the feature is off it will return "OFF".
If the request is loading it will returned undefined.
If the feature is loaded, it will return the feature.
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 | "OFF"
▸ useFeature<T>(featureReq, impressionId?, session?): DistributeFeature<Feature<T>> | undefined | "OFF"
React hook to get a single feature.
As compared to useImpression this only retrieves a single feature.
If the feature is off it will return "OFF".
If the request is loading it will returned undefined.
If the feature is loaded, it will return the feature.
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 | "OFF"
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 hook ensures react client hydration works correctly with SSR.
Parameters
| Name | Type |
|---|---|
json | SessionJSON |