@alanszp/split 20.4.4 → 20.5.0

package/babel.config.js

@@ -0,0 +1,7 @@
+// Used by Jest
+module.exports = {
+  presets: [
+    ["@babel/preset-env", { targets: { node: "current" } }],
+    "@babel/preset-typescript",
+  ],
+};

package/dist/document/codec.d.ts

@@ -0,0 +1,56 @@
+import { BuildDocumentInput, FeatureFlagDocument, FlagPositions, OrgBitmasks } from "./types";
+/**
+ * Encode the set of ON flags of a single org into a base64 bitmask string,
+ * using the same scheme as the JWT permissions.
+ *
+ * Flags whose treatment is `false`, or whose code is not present in
+ * `positions`, are skipped: the document only encodes flags whose bit position
+ * is known. Because positions are an input, an org can be encoded in isolation,
+ * which is what allows the document to be assembled org-by-org / in chunks.
+ */
+export declare function encodeOrg(treatments: Record<string, boolean>, positions: FlagPositions): string;
+/**
+ * Assemble a {@link FeatureFlagDocument} from precomputed flag positions and an
+ * already-encoded map of org bitmasks, computing the canonical hash.
+ *
+ * Use this when org bitmasks are produced incrementally (e.g. streaming orgs
+ * from the DB in chunks and calling {@link encodeOrg} per org); accumulate the
+ * results into an {@link OrgBitmasks} map and finalize once at the end.
+ *
+ * @param flags precomputed flag-code => bit position map.
+ * @param orgs map from org reference to its base64-encoded bitmask.
+ */
+export declare function finalizeDocument(flags: FlagPositions, orgs: OrgBitmasks): FeatureFlagDocument;
+/**
+ * Build a {@link FeatureFlagDocument} from precomputed flag positions and a
+ * list of org treatments.
+ *
+ * Bit positions are NOT derived here: they are an explicit input. Computing
+ * them (by convention, ordering flag codes by descending ON-frequency so the
+ * most common flags get the low positions and bitmasks stay small) is the
+ * backend's responsibility and is expected to be done with a single DB query
+ * (e.g. a window function over the flag ON counts). Keeping positions external
+ * makes the codec independent of the full org set, so the document can be
+ * encoded org-by-org / in chunks instead of requiring every org in memory.
+ *
+ * If the same org reference appears more than once in `input`, the last
+ * occurrence wins (its bitmask overwrites the previous one). Since positions
+ * are an input, a duplicate org can no longer skew anything else in the
+ * document.
+ *
+ * @param flags precomputed flag-code => bit position map.
+ * @param input list of `{ org, treatments }` entries.
+ * @returns the full feature flag document.
+ */
+export declare function buildDocument(flags: FlagPositions, input: BuildDocumentInput): FeatureFlagDocument;
+/**
+ * Decode whether a single flag is ON for a single org in the document.
+ *
+ * Returns `false` if the flag is not present in `doc.flags` or the org is not
+ * present in `doc.orgs`.
+ *
+ * @param doc the feature flag document.
+ * @param org the org reference to look up.
+ * @param flagCode the flag code to check.
+ */
+export declare function decodeFlagForOrg(doc: FeatureFlagDocument, org: string, flagCode: string): boolean;

package/dist/document/codec.js

@@ -0,0 +1,124 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.encodeOrg = encodeOrg;
+exports.finalizeDocument = finalizeDocument;
+exports.buildDocument = buildDocument;
+exports.decodeFlagForOrg = decodeFlagForOrg;
+const node_crypto_1 = require("node:crypto");
+const bitmask_1 = require("@alanszp/bitmask");
+/**
+ * Encode the set of ON flags of a single org into a base64 bitmask string,
+ * using the same scheme as the JWT permissions.
+ *
+ * Flags whose treatment is `false`, or whose code is not present in
+ * `positions`, are skipped: the document only encodes flags whose bit position
+ * is known. Because positions are an input, an org can be encoded in isolation,
+ * which is what allows the document to be assembled org-by-org / in chunks.
+ */
+function encodeOrg(treatments, positions) {
+    const bitmasks = [];
+    for (const [flagCode, isOn] of Object.entries(treatments)) {
+        if (!isOn) {
+            continue;
+        }
+        const position = positions[flagCode];
+        if (position === undefined) {
+            continue;
+        }
+        bitmasks.push(bitmask_1.BitmaskUtils.encodeFromPosition(position));
+    }
+    const combined = bitmask_1.BitmaskUtils.combineBitmasks(bitmasks);
+    return bitmask_1.BitmaskUtils.encodeToBase64(combined);
+}
+/**
+ * Serialize `flags` + `orgs` into a canonical, deterministic string with sorted
+ * keys, so that the same logical content always yields the same hash regardless
+ * of insertion order. The hash itself is never part of this serialization.
+ */
+function canonicalContent(flags, orgs) {
+    const sortKeys = (obj) => {
+        const out = {};
+        for (const key of Object.keys(obj).sort()) {
+            out[key] = obj[key];
+        }
+        return out;
+    };
+    return JSON.stringify({
+        flags: sortKeys(flags),
+        orgs: sortKeys(orgs),
+    });
+}
+/**
+ * Compute the sha256 (hex) of the canonical content.
+ */
+function hashContent(flags, orgs) {
+    return (0, node_crypto_1.createHash)("sha256")
+        .update(canonicalContent(flags, orgs))
+        .digest("hex");
+}
+/**
+ * Assemble a {@link FeatureFlagDocument} from precomputed flag positions and an
+ * already-encoded map of org bitmasks, computing the canonical hash.
+ *
+ * Use this when org bitmasks are produced incrementally (e.g. streaming orgs
+ * from the DB in chunks and calling {@link encodeOrg} per org); accumulate the
+ * results into an {@link OrgBitmasks} map and finalize once at the end.
+ *
+ * @param flags precomputed flag-code => bit position map.
+ * @param orgs map from org reference to its base64-encoded bitmask.
+ */
+function finalizeDocument(flags, orgs) {
+    return { hash: hashContent(flags, orgs), flags, orgs };
+}
+/**
+ * Build a {@link FeatureFlagDocument} from precomputed flag positions and a
+ * list of org treatments.
+ *
+ * Bit positions are NOT derived here: they are an explicit input. Computing
+ * them (by convention, ordering flag codes by descending ON-frequency so the
+ * most common flags get the low positions and bitmasks stay small) is the
+ * backend's responsibility and is expected to be done with a single DB query
+ * (e.g. a window function over the flag ON counts). Keeping positions external
+ * makes the codec independent of the full org set, so the document can be
+ * encoded org-by-org / in chunks instead of requiring every org in memory.
+ *
+ * If the same org reference appears more than once in `input`, the last
+ * occurrence wins (its bitmask overwrites the previous one). Since positions
+ * are an input, a duplicate org can no longer skew anything else in the
+ * document.
+ *
+ * @param flags precomputed flag-code => bit position map.
+ * @param input list of `{ org, treatments }` entries.
+ * @returns the full feature flag document.
+ */
+function buildDocument(flags, input) {
+    const orgs = {};
+    for (const { org, treatments } of input) {
+        orgs[org] = encodeOrg(treatments, flags);
+    }
+    return finalizeDocument(flags, orgs);
+}
+/**
+ * Decode whether a single flag is ON for a single org in the document.
+ *
+ * Returns `false` if the flag is not present in `doc.flags` or the org is not
+ * present in `doc.orgs`.
+ *
+ * @param doc the feature flag document.
+ * @param org the org reference to look up.
+ * @param flagCode the flag code to check.
+ */
+function decodeFlagForOrg(doc, org, flagCode) {
+    const position = doc.flags[flagCode];
+    if (position === undefined) {
+        return false;
+    }
+    const encoded = doc.orgs[org];
+    if (encoded === undefined) {
+        return false;
+    }
+    const bitmask = bitmask_1.BitmaskUtils.decodeFromBase64(encoded);
+    const check = bitmask_1.BitmaskUtils.encodeFromPosition(position);
+    return bitmask_1.BitmaskUtils.checkBitmask(bitmask, check);
+}
+//# sourceMappingURL=codec.js.map

package/dist/document/codec.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.js","sourceRoot":"","sources":["../../src/document/codec.ts"],"names":[],"mappings":"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"}

package/dist/document/codec.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/document/codec.test.js

@@ -0,0 +1,143 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+const bitmask_1 = require("@alanszp/bitmask");
+const codec_1 = require("./codec");
+describe("feature flag document codec", () => {
+    describe("encodeOrg", () => {
+        it("encodes only ON flags whose position is known", () => {
+            const positions = { a: 0, b: 1, c: 2 };
+            // a ON (pos 0 => bit 1), c ON (pos 2 => bit 4) => 0b101 = 5.
+            const encoded = (0, codec_1.encodeOrg)({ a: true, b: false, c: true }, positions);
+            expect(encoded).toBe(bitmask_1.BitmaskUtils.encodeToBase64(BigInt(5)));
+        });
+        it("skips flags missing from the positions map", () => {
+            const positions = { a: 0 };
+            // `unknown` has no position => ignored; only a (bit 1) is set.
+            const encoded = (0, codec_1.encodeOrg)({ a: true, unknown: true }, positions);
+            expect(encoded).toBe(bitmask_1.BitmaskUtils.encodeToBase64(BigInt(1)));
+        });
+        it("produces a small string when only low positions are set", () => {
+            const positions = { f0: 0, f1: 1, f2: 2, f3: 3, f4: 4 };
+            const common = (0, codec_1.encodeOrg)({ f0: true }, positions);
+            const rare = (0, codec_1.encodeOrg)({ f0: true, f1: true, f2: true, f3: true, f4: true }, positions);
+            expect(common).toBe(bitmask_1.BitmaskUtils.encodeToBase64(BigInt(1)));
+            expect(common.length).toBeLessThanOrEqual(rare.length);
+        });
+    });
+    describe("buildDocument", () => {
+        const positions = { a: 0, b: 1, c: 2 };
+        it("uses the positions it is given verbatim (does not derive them)", () => {
+            const doc = (0, codec_1.buildDocument)(positions, [
+                { org: "o1", treatments: { a: true } },
+            ]);
+            expect(doc.flags).toBe(positions);
+        });
+        it("round-trips every flag for every org back to its treatment", () => {
+            const input = [
+                { org: "o1", treatments: { a: true, b: false, c: true } },
+                { org: "o2", treatments: { a: false, b: true, c: false } },
+                { org: "o3", treatments: { a: true, b: true, c: true } },
+            ];
+            const doc = (0, codec_1.buildDocument)(positions, input);
+            for (const { org, treatments } of input) {
+                for (const [flagCode, expected] of Object.entries(treatments)) {
+                    expect((0, codec_1.decodeFlagForOrg)(doc, org, flagCode)).toBe(expected);
+                }
+            }
+        });
+        it("handles an org with no flags ON (empty bitmask)", () => {
+            const doc = (0, codec_1.buildDocument)(positions, [
+                { org: "empty", treatments: { a: false, b: false } },
+                { org: "full", treatments: { a: true, b: true } },
+            ]);
+            expect((0, codec_1.decodeFlagForOrg)(doc, "empty", "a")).toBe(false);
+            expect((0, codec_1.decodeFlagForOrg)(doc, "empty", "b")).toBe(false);
+            expect((0, codec_1.decodeFlagForOrg)(doc, "full", "a")).toBe(true);
+            expect((0, codec_1.decodeFlagForOrg)(doc, "full", "b")).toBe(true);
+        });
+        it("handles many flags / high positions correctly", () => {
+            const treatments = {};
+            const manyPositions = {};
+            for (let i = 0; i < 40; i++) {
+                manyPositions[`flag${i}`] = i;
+                treatments[`flag${i}`] = i % 2 === 0;
+            }
+            const doc = (0, codec_1.buildDocument)(manyPositions, [{ org: "o1", treatments }]);
+            for (const [flagCode, expected] of Object.entries(treatments)) {
+                expect((0, codec_1.decodeFlagForOrg)(doc, "o1", flagCode)).toBe(expected);
+            }
+        });
+        it("last occurrence wins when the same org appears twice", () => {
+            const doc = (0, codec_1.buildDocument)(positions, [
+                { org: "dup", treatments: { a: true, b: true } },
+                { org: "dup", treatments: { a: false, b: false } },
+            ]);
+            // Only the last entry is reflected; nothing else is skewed.
+            expect((0, codec_1.decodeFlagForOrg)(doc, "dup", "a")).toBe(false);
+            expect((0, codec_1.decodeFlagForOrg)(doc, "dup", "b")).toBe(false);
+            expect(Object.keys(doc.orgs)).toEqual(["dup"]);
+        });
+    });
+    describe("chunked assembly via encodeOrg + finalizeDocument", () => {
+        it("equals the single-shot buildDocument result", () => {
+            const positions = { a: 0, b: 1, c: 2 };
+            const input = [
+                { org: "o1", treatments: { a: true, b: false, c: true } },
+                { org: "o2", treatments: { a: false, b: true, c: false } },
+            ];
+            const oneShot = (0, codec_1.buildDocument)(positions, input);
+            // Simulate streaming orgs in separate chunks, encoding each on its own.
+            const orgs = {};
+            for (const { org, treatments } of input) {
+                orgs[org] = (0, codec_1.encodeOrg)(treatments, positions);
+            }
+            const chunked = (0, codec_1.finalizeDocument)(positions, orgs);
+            expect(chunked).toEqual(oneShot);
+            expect(chunked.hash).toBe(oneShot.hash);
+        });
+    });
+    describe("decodeFlagForOrg with missing entries", () => {
+        const doc = (0, codec_1.buildDocument)({ a: 0, b: 1 }, [{ org: "o1", treatments: { a: true, b: false } }]);
+        it("returns false for an unknown flag code", () => {
+            expect((0, codec_1.decodeFlagForOrg)(doc, "o1", "doesNotExist")).toBe(false);
+        });
+        it("returns false for an unknown org", () => {
+            expect((0, codec_1.decodeFlagForOrg)(doc, "unknownOrg", "a")).toBe(false);
+        });
+        it("returns false for an OFF flag", () => {
+            expect((0, codec_1.decodeFlagForOrg)(doc, "o1", "b")).toBe(false);
+        });
+    });
+    describe("hash", () => {
+        const positions = { x: 0, y: 1 };
+        it("is a 64-char hex sha256 string", () => {
+            const doc = (0, codec_1.buildDocument)(positions, [
+                { org: "o1", treatments: { x: true } },
+            ]);
+            expect(doc.hash).toMatch(/^[0-9a-f]{64}$/);
+        });
+        it("is deterministic regardless of org/flag insertion order", () => {
+            const a = (0, codec_1.buildDocument)({ x: 0, y: 1 }, [
+                { org: "o1", treatments: { x: true, y: false } },
+                { org: "o2", treatments: { x: false, y: true } },
+            ]);
+            const b = (0, codec_1.buildDocument)({ y: 1, x: 0 }, [
+                { org: "o2", treatments: { y: true, x: false } },
+                { org: "o1", treatments: { y: false, x: true } },
+            ]);
+            expect(a.flags).toEqual(b.flags);
+            expect(a.orgs).toEqual(b.orgs);
+            expect(a.hash).toBe(b.hash);
+        });
+        it("changes when content changes", () => {
+            const a = (0, codec_1.buildDocument)(positions, [
+                { org: "o1", treatments: { x: true } },
+            ]);
+            const b = (0, codec_1.buildDocument)(positions, [
+                { org: "o1", treatments: { x: false } },
+            ]);
+            expect(a.hash).not.toBe(b.hash);
+        });
+    });
+});
+//# sourceMappingURL=codec.test.js.map

package/dist/document/codec.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"codec.test.js","sourceRoot":"","sources":["../../src/document/codec.test.ts"],"names":[],"mappings":"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"}

package/dist/document/index.d.ts

@@ -0,0 +1,2 @@
+export * from "./types";
+export * from "./codec";

package/dist/document/index.js

@@ -0,0 +1,19 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+__exportStar(require("./types"), exports);
+__exportStar(require("./codec"), exports);
+//# sourceMappingURL=index.js.map

package/dist/document/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/document/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,0CAAwB;AACxB,0CAAwB"}

package/dist/document/types.d.ts

@@ -0,0 +1,63 @@
+/**
+ * Feature flag document types.
+ *
+ * The document is a deterministic, self-contained snapshot of which feature
+ * flags are ON for which orgs. It is meant to be serialized (e.g. to S3) and
+ * decoded by clients without needing to talk to Split.io.
+ *
+ * Encoding scheme (mirrors the JWT permissions scheme):
+ * - Each flag is assigned a bit `position` (see {@link FlagPositions}).
+ * - For each org, the set of ON flags is turned into a bitmask by OR-ing
+ *   `1 << position` for every ON flag, and that bigint is base64-encoded using
+ *   `@alanszp/bitmask`.
+ * - Positions are an INPUT to the codec, not derived by it. By convention the
+ *   backend assigns them by descending ON-frequency (the flag that is ON for
+ *   the most orgs gets position 0), computed with a single DB query. This keeps
+ *   the BigInt magnitude (and thus the encoded strings) small, because the most
+ *   common bits live in the low positions and orgs that only have rare flags
+ *   get short strings. Keeping positions external lets the document be encoded
+ *   org-by-org / in chunks instead of requiring every org in memory at once.
+ */
+/**
+ * Map from flag code to its assigned bit position (0-based).
+ */
+export type FlagPositions = Record<string, number>;
+/**
+ * Map from org reference to the base64-encoded bitmask of its ON flags.
+ */
+export type OrgBitmasks = Record<string, string>;
+/**
+ * The full feature flag document.
+ */
+export interface FeatureFlagDocument {
+    /**
+     * sha256 (hex) of the canonical, deterministic serialization of `flags` +
+     * `orgs`. Does NOT include itself in the computation.
+     */
+    hash: string;
+    /**
+     * Map from flag code to its bit position. Positions are computed by the
+     * backend (by convention, descending ON-frequency => most-ON flag gets
+     * position 0) and fed into the codec as an input.
+     */
+    flags: FlagPositions;
+    /**
+     * Map from org reference to its base64-encoded ON-flags bitmask.
+     */
+    orgs: OrgBitmasks;
+}
+/**
+ * Input entry for {@link buildDocument}: one org and the on/off treatment of
+ * each flag for that org. Flags whose treatment is `false` (or missing) are
+ * considered OFF.
+ */
+export interface OrgTreatments {
+    /** Org reference. */
+    org: string;
+    /** Map from flag code to whether the flag is ON for this org. */
+    treatments: Record<string, boolean>;
+}
+/**
+ * Full input for {@link buildDocument}.
+ */
+export type BuildDocumentInput = OrgTreatments[];

package/dist/document/types.js

@@ -0,0 +1,23 @@
+"use strict";
+/**
+ * Feature flag document types.
+ *
+ * The document is a deterministic, self-contained snapshot of which feature
+ * flags are ON for which orgs. It is meant to be serialized (e.g. to S3) and
+ * decoded by clients without needing to talk to Split.io.
+ *
+ * Encoding scheme (mirrors the JWT permissions scheme):
+ * - Each flag is assigned a bit `position` (see {@link FlagPositions}).
+ * - For each org, the set of ON flags is turned into a bitmask by OR-ing
+ *   `1 << position` for every ON flag, and that bigint is base64-encoded using
+ *   `@alanszp/bitmask`.
+ * - Positions are an INPUT to the codec, not derived by it. By convention the
+ *   backend assigns them by descending ON-frequency (the flag that is ON for
+ *   the most orgs gets position 0), computed with a single DB query. This keeps
+ *   the BigInt magnitude (and thus the encoded strings) small, because the most
+ *   common bits live in the low positions and orgs that only have rare flags
+ *   get short strings. Keeping positions external lets the document be encoded
+ *   org-by-org / in chunks instead of requiring every org in memory at once.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=types.js.map

package/dist/document/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/document/types.ts"],"names":[],"mappings":";AAAA;;;;;;;;;;;;;;;;;;;GAmBG"}

package/dist/index.d.ts

@@ -1 +1,2 @@
 export * from "./client";
+export * from "./document";

package/dist/index.js

@@ -16,4 +16,5 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 Object.defineProperty(exports, "__esModule", { value: true });
 // Adding dummy code to deploy package
 __exportStar(require("./client"), exports);
+__exportStar(require("./document"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sCAAsC;AACtC,2CAAyB"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA,sCAAsC;AACtC,2CAAyB;AACzB,6CAA2B"}

package/jest.config.js

@@ -0,0 +1,10 @@
+module.exports = {
+  collectCoverageFrom: ["src/**/*.{js,jsx,ts,tsx}"],
+  roots: ["<rootDir>/src/"],
+  clearMocks: true,
+  resetMocks: true,
+  testEnvironment: "node",
+  moduleNameMapper: {
+    "@/(.*)": "<rootDir>/src/$1",
+  },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alanszp/split",
-  "version": "20.4.4",
+  "version": "20.5.0",
   "description": "Alan's split client",
   "main": "dist/index.js",
   "typings": "dist/index.d.ts",
@@ -13,26 +13,34 @@
     "compile-watch": "tsc -w",
     "build": "pnpm run compile",
     "prepack": "pnpm run build",
+    "test": "TZ=Etc/UTC jest",
     "yalc-publish": "pnpm run yalc publish"
   },
   "peerDependencies": {
     "@alanszp/logger": "*"
   },
   "devDependencies": {
-    "@alanszp/logger": "^20.4.4",
+    "@alanszp/logger": "^20.5.0",
+    "@babel/core": "^7.24.0",
+    "@babel/preset-env": "^7.29.5",
+    "@babel/preset-typescript": "^7.23.3",
+    "@types/jest": "^29.5.12",
     "@types/lodash": "^4.14.170",
     "@types/node": "^24.0.0",
+    "babel-jest": "^29.7.0",
+    "jest": "^29.7.0",
     "ts-node": "^10.0.0",
     "tslint": "^6.1.3",
     "typescript": "^5.9.3"
   },
   "dependencies": {
-    "@alanszp/core": "^20.4.4",
-    "@alanszp/shared-context": "^20.4.4",
-    "@alanszp/typeorm": "^20.4.4",
+    "@alanszp/bitmask": "^20.5.0",
+    "@alanszp/core": "^20.5.0",
+    "@alanszp/shared-context": "^20.5.0",
+    "@alanszp/typeorm": "^20.5.0",
     "@splitsoftware/splitio": "^10.25.1",
     "ioredis": "^5.9.3",
     "lodash": "^4.17.23"
   },
-  "gitHead": "113b57dc0fa86390b1b9ea9bdd9bc219825544f4"
+  "gitHead": "db82dba6b9d0976f56b256be6d552131b44217f6"
 }

package/tsconfig.json

@@ -4,7 +4,7 @@
     "outDir": "dist",
     "module": "commonjs",
     "target": "es6",
-    "types": ["node"],
+    "types": ["jest", "node"],
     "esModuleInterop": true,
     "sourceMap": true,