posthog-js-lite - npm Package Compare versions

Comparing version 2.6.2 to 3.0.0-beta.1

CHANGELOG.md

@@ -0,1 +1,10 @@
+# 3.0.0-beta.1 - 2024-03-04
+
+- Removes the `enable` option. You can now specify `defaultOptIn: false` to start the SDK opted out of tracking
+- Adds a `disabled` option and the ability to change it later via `posthog.disabled = true`. Useful for disabling PostHog tracking for example in a testing environment without having complex conditional checking
+- Many methods such as `capture` and `identify` no longer return the `this` object instead returning nothing
+- Fixes some typos in types
+- `shutdown` and `shutdownAsync` takes a `shutdownTimeoutMs` param with a default of 30000 (30s). This is the time to wait for flushing events before shutting down the client. If the timeout is reached, the client will be shut down regardless of pending events.
+- Adds a new `featureFlagsRequestTimeoutMs` timeout parameter for feature flags which defaults to 10 seconds.
+
 # 2.6.2 - 2024-02-15
@@ -2,0 +11,0 @@

lib/index.d.ts

@@ -1,8 +0,17 @@
-declare type PosthogCoreOptions = {
+declare type PostHogCoreOptions = {
+    /** PostHog API host, usually 'https://app.posthog.com' or 'https://eu.posthog.com' */
     host?: string;
+    /** The number of events to queue before sending to PostHog (flushing) */
     flushAt?: number;
+    /** The interval in milliseconds between periodic flushes */
     flushInterval?: number;
-    enable?: boolean;
+    /** If set to true the SDK is essentially disabled (useful for local environments where you don't want to track anything) */
+    disabled?: boolean;
+    /** If set to false the SDK will not track until the `optIn` function is called. */
+    defaultOptIn?: boolean;
+    /** Whether to track that `getFeatureFlag` was called (used by Experiments) */
     sendFeatureFlagEvent?: boolean;
+    /** Whether to load feature flags when initialized or not */
     preloadFeatureFlags?: boolean;
+    /** Option to bootstrap the library with given distinctId and feature flags */
     bootstrap?: {
@@ -14,6 +23,13 @@ distinctId?: string;
     };
+    /** How many times we will retry HTTP requests. Defaults to 3. */
     fetchRetryCount?: number;
+    /** The delay between HTTP request retries, Defaults to 3 seconds. */
     fetchRetryDelay?: number;
+    /** Timeout in milliseconds for any calls. Defaults to 10 seconds. */
     requestTimeout?: number;
+    /** Timeout in milliseconds for feature flag calls. Defaults to 10 seconds for stateful clients, and 3 seconds for stateless. */
+    featureFlagsRequestTimeoutMs?: number;
+    /** For Session Analysis how long before we expire a session (defaults to 30 mins) */
     sessionExpirationTimeSeconds?: number;
+    /** Whether to post events to PostHog in JSON or compressed format */
     captureMode?: 'json' | 'form';
@@ -97,5 +113,5 @@ disableGeoip?: boolean;
 interface RetriableOptions {
-    retryCount?: number;
-    retryDelay?: number;
-    retryCheck?: (err: any) => boolean;
+    retryCount: number;
+    retryDelay: number;
+    retryCheck: (err: any) => boolean;
 }
@@ -118,7 +134,8 @@
     private requestTimeout;
+    private featureFlagsRequestTimeoutMs;
     private captureMode;
     private removeDebugCallback?;
-    private debugMode;
     private disableGeoip;
-    private _optoutOverride;
+    disabled: boolean;
+    private defaultOptIn;
     private pendingPromises;
@@ -128,2 +145,4 @@ protected _events: SimpleEventEmitter;
     protected _retryOptions: RetriableOptions;
+    protected _initPromise: Promise<void>;
+    protected _isInitialized: boolean;
     abstract fetch(url: string, options: PostHogFetchOptions): Promise<PostHogFetchResponse>;
@@ -135,9 +154,11 @@ abstract getLibraryId(): string;
     abstract setPersistedProperty<T>(key: PostHogPersistedProperty, value: T | null): void;
-    constructor(apiKey: string, options?: PosthogCoreOptions);
+    constructor(apiKey: string, options?: PostHogCoreOptions);
+    protected wrap(fn: () => void): void;
     protected getCommonEventProperties(): any;
     get optedOut(): boolean;
-    optIn(): void;
-    optOut(): void;
+    optIn(): Promise<void>;
+    optOut(): Promise<void>;
     on(event: string, cb: (...args: any[]) => void): () => void;
     debug(enabled?: boolean): void;
+    get isDebug(): boolean;
     private buildPayload;
@@ -148,13 +169,13 @@ protected addPendingPromise(promise: Promise<any>): void;
      ***/
-    protected identifyStateless(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
+    protected identifyStateless(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     protected captureStateless(distinctId: string, event: string, properties?: {
         [key: string]: any;
-    }, options?: PostHogCaptureOptions): this;
+    }, options?: PostHogCaptureOptions): void;
     protected aliasStateless(alias: string, distinctId: string, properties?: {
         [key: string]: any;
-    }, options?: PostHogCaptureOptions): this;
+    }, options?: PostHogCaptureOptions): void;
     /***
      *** GROUPS
      ***/
-    protected groupIdentifyStateless(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions, distinctId?: string, eventProperties?: PostHogEventProperties): this;
+    protected groupIdentifyStateless(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions, distinctId?: string, eventProperties?: PostHogEventProperties): void;
     /***
@@ -180,4 +201,4 @@ *** FEATURE FLAGS
     private fetchWithRetry;
-    shutdownAsync(): Promise<void>;
-    shutdown(): void;
+    shutdownAsync(shutdownTimeoutMs?: number): Promise<void>;
+    shutdown(shutdownTimeoutMs?: number): void;
 }
@@ -190,4 +211,4 @@ declare abstract class PostHogCore extends PostHogCoreStateless {
     protected sessionProps: PostHogEventProperties;
-    constructor(apiKey: string, options?: PosthogCoreOptions);
-    protected setupBootstrap(options?: Partial<PosthogCoreOptions>): void;
+    constructor(apiKey: string, options?: PostHogCoreOptions);
+    protected setupBootstrap(options?: Partial<PostHogCoreOptions>): void;
     private get props();
@@ -200,11 +221,20 @@ private set props(value);
     protected getCommonEventProperties(): any;
-    enrichProperties(properties?: PostHogEventProperties): any;
-    getSessionId(): string | undefined;
+    private enrichProperties;
+    /**
+     * * @returns {string} The stored session ID for the current session. This may be an empty string if the client is not yet fully initialized.
+     */
+    getSessionId(): string;
     resetSessionId(): void;
+    /**
+     * * @returns {string} The stored anonymous ID. This may be an empty string if the client is not yet fully initialized.
+     */
     getAnonymousId(): string;
+    /**
+     * * @returns {string} The stored distinct ID. This may be an empty string if the client is not yet fully initialized.
+     */
     getDistinctId(): string;
-    unregister(property: string): void;
+    unregister(property: string): Promise<void>;
     register(properties: {
         [key: string]: any;
-    }): void;
+    }): Promise<void>;
     registerForSession(properties: {
@@ -217,8 +247,8 @@ [key: string]: any;
      ***/
-    identify(distinctId?: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
+    identify(distinctId?: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     capture(event: string, properties?: {
         [key: string]: any;
-    }, options?: PostHogCaptureOptions): this;
-    alias(alias: string): this;
-    autocapture(eventType: string, elements: PostHogAutocaptureElement[], properties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
+    }, options?: PostHogCaptureOptions): void;
+    alias(alias: string): void;
+    autocapture(eventType: string, elements: PostHogAutocaptureElement[], properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     /***
@@ -229,5 +259,5 @@ *** GROUPS
         [type: string]: string | number;
-    }): this;
-    group(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
-    groupIdentify(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
+    }): void;
+    group(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
+    groupIdentify(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     /***
@@ -238,3 +268,3 @@ * PROPERTIES
         [type: string]: string;
-    }): this;
+    }): void;
     resetPersonPropertiesForFlags(): void;
@@ -244,6 +274,6 @@ /** @deprecated - Renamed to setPersonPropertiesForFlags */
         [type: string]: string;
-    }): this;
+    }): void;
     setGroupPropertiesForFlags(properties: {
         [type: string]: Record<string, string>;
-    }): this;
+    }): void;
     resetGroupPropertiesForFlags(): void;
@@ -253,3 +283,3 @@ /** @deprecated - Renamed to setGroupPropertiesForFlags */
         [type: string]: Record<string, string>;
-    }): this;
+    }): void;
     /***
@@ -275,3 +305,3 @@ *** FEATURE FLAGS
     onFeatureFlag(key: string, cb: (value: string | boolean) => void): () => void;
-    overrideFeatureFlag(flags: PostHogDecideResponse['featureFlags'] | null): void;
+    overrideFeatureFlag(flags: PostHogDecideResponse['featureFlags'] | null): Promise<void>;
 }
@@ -283,3 +313,3 @@
     persistence_name?: string;
-} & PosthogCoreOptions;
+} & PostHogCoreOptions;
 
@@ -286,0 +316,0 @@ declare class PostHog extends PostHogCore {

lib/posthog-core/src/index.d.ts

@@ -1,2 +0,2 @@
-import { PostHogFetchOptions, PostHogFetchResponse, PostHogAutocaptureElement, PostHogDecideResponse, PosthogCoreOptions, PostHogEventProperties, PostHogPersistedProperty, PostHogCaptureOptions, JsonType } from './types';
+import { PostHogFetchOptions, PostHogFetchResponse, PostHogAutocaptureElement, PostHogDecideResponse, PostHogCoreOptions, PostHogEventProperties, PostHogPersistedProperty, PostHogCaptureOptions, JsonType } from './types';
 import { RetriableOptions } from './utils';
@@ -12,7 +12,8 @@ export * as utils from './utils';
     private requestTimeout;
+    private featureFlagsRequestTimeoutMs;
     private captureMode;
     private removeDebugCallback?;
-    private debugMode;
     private disableGeoip;
-    private _optoutOverride;
+    disabled: boolean;
+    private defaultOptIn;
     private pendingPromises;
@@ -22,2 +23,4 @@ protected _events: SimpleEventEmitter;
     protected _retryOptions: RetriableOptions;
+    protected _initPromise: Promise<void>;
+    protected _isInitialized: boolean;
     abstract fetch(url: string, options: PostHogFetchOptions): Promise<PostHogFetchResponse>;
@@ -29,9 +32,11 @@ abstract getLibraryId(): string;
     abstract setPersistedProperty<T>(key: PostHogPersistedProperty, value: T | null): void;
-    constructor(apiKey: string, options?: PosthogCoreOptions);
+    constructor(apiKey: string, options?: PostHogCoreOptions);
+    protected wrap(fn: () => void): void;
     protected getCommonEventProperties(): any;
     get optedOut(): boolean;
-    optIn(): void;
-    optOut(): void;
+    optIn(): Promise<void>;
+    optOut(): Promise<void>;
     on(event: string, cb: (...args: any[]) => void): () => void;
     debug(enabled?: boolean): void;
+    get isDebug(): boolean;
     private buildPayload;
@@ -42,13 +47,13 @@ protected addPendingPromise(promise: Promise<any>): void;
      ***/
-    protected identifyStateless(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
+    protected identifyStateless(distinctId: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     protected captureStateless(distinctId: string, event: string, properties?: {
         [key: string]: any;
-    }, options?: PostHogCaptureOptions): this;
+    }, options?: PostHogCaptureOptions): void;
     protected aliasStateless(alias: string, distinctId: string, properties?: {
         [key: string]: any;
-    }, options?: PostHogCaptureOptions): this;
+    }, options?: PostHogCaptureOptions): void;
     /***
      *** GROUPS
      ***/
-    protected groupIdentifyStateless(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions, distinctId?: string, eventProperties?: PostHogEventProperties): this;
+    protected groupIdentifyStateless(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions, distinctId?: string, eventProperties?: PostHogEventProperties): void;
     /***
@@ -74,4 +79,4 @@ *** FEATURE FLAGS
     private fetchWithRetry;
-    shutdownAsync(): Promise<void>;
-    shutdown(): void;
+    shutdownAsync(shutdownTimeoutMs?: number): Promise<void>;
+    shutdown(shutdownTimeoutMs?: number): void;
 }
@@ -84,4 +89,4 @@ export declare abstract class PostHogCore extends PostHogCoreStateless {
     protected sessionProps: PostHogEventProperties;
-    constructor(apiKey: string, options?: PosthogCoreOptions);
-    protected setupBootstrap(options?: Partial<PosthogCoreOptions>): void;
+    constructor(apiKey: string, options?: PostHogCoreOptions);
+    protected setupBootstrap(options?: Partial<PostHogCoreOptions>): void;
     private get props();
@@ -94,11 +99,20 @@ private set props(value);
     protected getCommonEventProperties(): any;
-    enrichProperties(properties?: PostHogEventProperties): any;
-    getSessionId(): string | undefined;
+    private enrichProperties;
+    /**
+     * * @returns {string} The stored session ID for the current session. This may be an empty string if the client is not yet fully initialized.
+     */
+    getSessionId(): string;
     resetSessionId(): void;
+    /**
+     * * @returns {string} The stored anonymous ID. This may be an empty string if the client is not yet fully initialized.
+     */
     getAnonymousId(): string;
+    /**
+     * * @returns {string} The stored distinct ID. This may be an empty string if the client is not yet fully initialized.
+     */
     getDistinctId(): string;
-    unregister(property: string): void;
+    unregister(property: string): Promise<void>;
     register(properties: {
         [key: string]: any;
-    }): void;
+    }): Promise<void>;
     registerForSession(properties: {
@@ -111,8 +125,8 @@ [key: string]: any;
      ***/
-    identify(distinctId?: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
+    identify(distinctId?: string, properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     capture(event: string, properties?: {
         [key: string]: any;
-    }, options?: PostHogCaptureOptions): this;
-    alias(alias: string): this;
-    autocapture(eventType: string, elements: PostHogAutocaptureElement[], properties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
+    }, options?: PostHogCaptureOptions): void;
+    alias(alias: string): void;
+    autocapture(eventType: string, elements: PostHogAutocaptureElement[], properties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     /***
@@ -123,5 +137,5 @@ *** GROUPS
         [type: string]: string | number;
-    }): this;
-    group(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
-    groupIdentify(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): this;
+    }): void;
+    group(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
+    groupIdentify(groupType: string, groupKey: string | number, groupProperties?: PostHogEventProperties, options?: PostHogCaptureOptions): void;
     /***
@@ -132,3 +146,3 @@ * PROPERTIES
         [type: string]: string;
-    }): this;
+    }): void;
     resetPersonPropertiesForFlags(): void;
@@ -138,6 +152,6 @@ /** @deprecated - Renamed to setPersonPropertiesForFlags */
         [type: string]: string;
-    }): this;
+    }): void;
     setGroupPropertiesForFlags(properties: {
         [type: string]: Record<string, string>;
-    }): this;
+    }): void;
     resetGroupPropertiesForFlags(): void;
@@ -147,3 +161,3 @@ /** @deprecated - Renamed to setGroupPropertiesForFlags */
         [type: string]: Record<string, string>;
-    }): this;
+    }): void;
     /***
@@ -169,5 +183,5 @@ *** FEATURE FLAGS
     onFeatureFlag(key: string, cb: (value: string | boolean) => void): () => void;
-    overrideFeatureFlag(flags: PostHogDecideResponse['featureFlags'] | null): void;
+    overrideFeatureFlag(flags: PostHogDecideResponse['featureFlags'] | null): Promise<void>;
 }
 export * from './types';
 export { LZString };

lib/posthog-core/src/types.d.ts

@@ -1,8 +0,17 @@
-export declare type PosthogCoreOptions = {
+export declare type PostHogCoreOptions = {
+    /** PostHog API host, usually 'https://app.posthog.com' or 'https://eu.posthog.com' */
     host?: string;
+    /** The number of events to queue before sending to PostHog (flushing) */
     flushAt?: number;
+    /** The interval in milliseconds between periodic flushes */
     flushInterval?: number;
-    enable?: boolean;
+    /** If set to true the SDK is essentially disabled (useful for local environments where you don't want to track anything) */
+    disabled?: boolean;
+    /** If set to false the SDK will not track until the `optIn` function is called. */
+    defaultOptIn?: boolean;
+    /** Whether to track that `getFeatureFlag` was called (used by Experiments) */
     sendFeatureFlagEvent?: boolean;
+    /** Whether to load feature flags when initialized or not */
     preloadFeatureFlags?: boolean;
+    /** Option to bootstrap the library with given distinctId and feature flags */
     bootstrap?: {
@@ -14,6 +23,13 @@ distinctId?: string;
     };
+    /** How many times we will retry HTTP requests. Defaults to 3. */
     fetchRetryCount?: number;
+    /** The delay between HTTP request retries, Defaults to 3 seconds. */
     fetchRetryDelay?: number;
+    /** Timeout in milliseconds for any calls. Defaults to 10 seconds. */
     requestTimeout?: number;
+    /** Timeout in milliseconds for feature flag calls. Defaults to 10 seconds for stateful clients, and 3 seconds for stateless. */
+    featureFlagsRequestTimeoutMs?: number;
+    /** For Session Analysis how long before we expire a session (defaults to 30 mins) */
     sessionExpirationTimeSeconds?: number;
+    /** Whether to post events to PostHog in JSON or compressed format */
     captureMode?: 'json' | 'form';
@@ -96,3 +112,3 @@ disableGeoip?: boolean;
 };
-export declare type PosthogFlagsAndPayloadsResponse = {
+export declare type PostHogFlagsAndPayloadsResponse = {
     featureFlags: PostHogDecideResponse['featureFlags'];
@@ -99,0 +115,0 @@ featureFlagPayloads: PostHogDecideResponse['featureFlagPayloads'];

lib/posthog-core/src/utils.d.ts

 export declare function assert(truthyValue: any, message: string): void;
 export declare function removeTrailingSlash(url: string): string;
 export interface RetriableOptions {
-    retryCount?: number;
-    retryDelay?: number;
-    retryCheck?: (err: any) => boolean;
+    retryCount: number;
+    retryDelay: number;
+    retryCheck: (err: any) => boolean;
 }
-export declare function retriable<T>(fn: () => Promise<T>, props?: RetriableOptions): Promise<T>;
+export declare function retriable<T>(fn: () => Promise<T>, props: RetriableOptions): Promise<T>;
 export declare function currentTimestamp(): number;
 export declare function currentISOTime(): string;
 export declare function safeSetTimeout(fn: () => void, timeout: number): any;
+export declare const isPromise: (obj: any) => obj is Promise<any>;

lib/posthog-web/src/types.d.ts

@@ -1,2 +0,2 @@
-import { PosthogCoreOptions } from '../../posthog-core/src';
+import { PostHogCoreOptions } from '../../posthog-core/src';
 export declare type PostHogOptions = {
@@ -6,2 +6,2 @@ autocapture?: boolean;
     persistence_name?: string;
-} & PosthogCoreOptions;
+} & PostHogCoreOptions;

package.json

 {
   "name": "posthog-js-lite",
-  "version": "2.6.2",
+  "version": "3.0.0-beta.1",
   "main": "lib/index.cjs.js",
@@ -5,0 +5,0 @@ "module": "lib/index.esm.js",

src/types.ts

@@ -1,2 +0,2 @@
-import { PosthogCoreOptions } from '../../posthog-core/src'
+import { PostHogCoreOptions } from '../../posthog-core/src'
 
@@ -7,2 +7,2 @@ export type PostHogOptions = {
   persistence_name?: string
-} & PosthogCoreOptions
+} & PostHogCoreOptions

test/posthog-web.spec.ts

@@ -5,5 +5,6 @@ /**
 
+import { waitForPromises } from 'posthog-core/test/test-utils/test-utils'
 import { PostHog } from '..'
 
-describe('PosthogWeb', () => {
+describe('PostHogWeb', () => {
   let fetch: jest.Mock
@@ -45,3 +46,3 @@ jest.useRealTimers()
   describe('init', () => {
-    it('should initialise', () => {
+    it('should initialise', async () => {
       const posthog = new PostHog('TEST_API_KEY', {
@@ -53,2 +54,3 @@ flushAt: 1,
       posthog.capture('test')
+      await waitForPromises()
 
@@ -63,2 +65,4 @@ expect(fetch).toHaveBeenCalledTimes(2)
 
+      await waitForPromises()
+
       expect(fetch).toHaveBeenCalledWith('https://app.posthog.com/decide/?v=3', {
@@ -65,0 +69,0 @@ body: JSON.stringify({

tsconfig.json

 {
   "extends": "../tsconfig.json",
   "compilerOptions": {
-    "lib": ["DOM", "ES2015", "ES2022.Error"]
+    "lib": ["DOM", "ES2020", "ES2022.Error"]
   }
 }

New alerts

No v1

Quality

Package is not semver >=1. This means it is not stable and does not support ^ ranges.

Found 1 instance in 1 package

Worsened metrics

Total package byte prevSize

540446

decreased by-13.19%

Lines of code

5620

decreased by-4.87%

Number of low quality alerts

2

increased by100%

No dependency changes