@khanacademy/perseus-core 3.2.0 → 3.3.0

package/dist/parse-perseus-json/error-tracking-parse-context.d.ts

@@ -0,0 +1,9 @@
+import type { ParseContext, Mismatch, PathSegment } from "./parser-types";
+import type { Failure, Success } from "./result";
+export declare class ErrorTrackingParseContext implements ParseContext {
+    private readonly path;
+    constructor(path: PathSegment[]);
+    failure(expected: string | string[], badValue: unknown): Failure<Mismatch[]>;
+    forSubtree(key: PathSegment): ParseContext;
+    success<T>(value: T): Success<T>;
+}

package/dist/parse-perseus-json/exhaustive-test-tool/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env -S node -r @swc-node/register
+export {};

package/dist/parse-perseus-json/general-purpose-parsers/any.d.ts

@@ -0,0 +1,2 @@
+import type { Parser } from "../parser-types";
+export declare const any: Parser<any>;

package/dist/parse-perseus-json/general-purpose-parsers/array.d.ts

@@ -0,0 +1,2 @@
+import type { Parser } from "../parser-types";
+export declare function array<T>(elementParser: Parser<T>): Parser<T[]>;

package/dist/parse-perseus-json/general-purpose-parsers/array.typetest.d.ts

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

package/dist/parse-perseus-json/general-purpose-parsers/boolean.d.ts

@@ -0,0 +1,2 @@
+import type { ParseContext, ParseResult } from "../parser-types";
+export declare function boolean(rawValue: unknown, ctx: ParseContext): ParseResult<boolean>;

package/dist/parse-perseus-json/general-purpose-parsers/constant.d.ts

@@ -0,0 +1,4 @@
+import type { Parser } from "../parser-types";
+type Primitive = string | number | boolean | null | undefined;
+export declare function constant<T extends Primitive>(acceptedValue: T): Parser<T>;
+export {};

package/dist/parse-perseus-json/general-purpose-parsers/convert.d.ts

@@ -0,0 +1,2 @@
+import type { PartialParser } from "../parser-types";
+export declare function convert<A, B>(f: (value: A) => B): PartialParser<A, B>;

package/dist/parse-perseus-json/general-purpose-parsers/defaulted.d.ts

@@ -0,0 +1,2 @@
+import type { Parser } from "../parser-types";
+export declare function defaulted<T, Default>(parser: Parser<T>, fallback: (missingValue: null | undefined) => Default): Parser<T | Default>;

package/dist/parse-perseus-json/general-purpose-parsers/discriminated-union.d.ts

@@ -0,0 +1,21 @@
+import type { Parser } from "../parser-types";
+type Primitive = number | string | boolean | null | undefined;
+/**
+ * discriminatedUnion() should be preferred over union() when parsing a
+ * discriminated union type, because discriminatedUnion() produces more
+ * understandable failure messages. It takes the discriminant as the source of
+ * truth for which variant is to be parsed, and expects the other data to match
+ * that variant.
+ */
+export declare function discriminatedUnionOn<DK extends string>(discriminantKey: DK): DiscriminatedUnionBuilder<DK, never>;
+declare class DiscriminatedUnionBuilder<DK extends string, Union extends {
+    [k in DK]: Primitive;
+}> {
+    private discriminantKey;
+    parser: Parser<Union>;
+    constructor(discriminantKey: DK, parser: Parser<Union>);
+    withBranch<Variant extends {
+        [k in DK]: Primitive;
+    }>(discriminantValue: Primitive, parseNewVariant: Parser<Variant>): DiscriminatedUnionBuilder<DK, Union | Variant>;
+}
+export {};

package/dist/parse-perseus-json/general-purpose-parsers/discriminated-union.typetest.d.ts

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

package/dist/parse-perseus-json/general-purpose-parsers/enumeration.d.ts

@@ -0,0 +1,2 @@
+import type { Parser } from "../parser-types";
+export declare function enumeration<T extends readonly string[]>(...acceptedValues: T): Parser<T[number]>;

package/dist/parse-perseus-json/general-purpose-parsers/enumeration.typetest.d.ts

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

package/dist/parse-perseus-json/general-purpose-parsers/index.d.ts

@@ -0,0 +1,17 @@
+export * from "./any";
+export * from "./array";
+export * from "./boolean";
+export * from "./constant";
+export * from "./enumeration";
+export * from "./is-object";
+export * from "./nullable";
+export * from "./number";
+export * from "./object";
+export * from "./optional";
+export * from "./pair";
+export * from "./pipe-parsers";
+export * from "./record";
+export * from "./string";
+export * from "./trio";
+export * from "./union";
+export * from "./unknown";

package/dist/parse-perseus-json/general-purpose-parsers/is-object.d.ts

@@ -0,0 +1 @@
+export declare function isObject(x: unknown): x is Record<keyof any, unknown>;

package/dist/parse-perseus-json/general-purpose-parsers/nullable.d.ts

@@ -0,0 +1,2 @@
+import type { Parser } from "../parser-types";
+export declare function nullable<T>(parseValue: Parser<T>): Parser<T | null>;

package/dist/parse-perseus-json/general-purpose-parsers/number.d.ts

@@ -0,0 +1,2 @@
+import type { Parser } from "../parser-types";
+export declare const number: Parser<number>;

package/dist/parse-perseus-json/general-purpose-parsers/object.d.ts

@@ -0,0 +1,6 @@
+import type { ParsedValue, Parser } from "../parser-types";
+type ObjectSchema = Record<keyof any, Parser<any>>;
+export declare function object<S extends ObjectSchema>(schema: S): Parser<{
+    [K in keyof S]: ParsedValue<S[K]>;
+}>;
+export {};

package/dist/parse-perseus-json/general-purpose-parsers/optional.d.ts

@@ -0,0 +1,2 @@
+import type { Parser } from "../parser-types";
+export declare function optional<T>(parseValue: Parser<T>): Parser<T | undefined>;

package/dist/parse-perseus-json/general-purpose-parsers/pair.d.ts

@@ -0,0 +1,2 @@
+import type { Parser } from "../parser-types";
+export declare function pair<A, B>(parseA: Parser<A>, parseB: Parser<B>): Parser<[A, B]>;

package/dist/parse-perseus-json/general-purpose-parsers/pipe-parsers.d.ts

@@ -0,0 +1,7 @@
+import type { Parser, PartialParser } from "../parser-types";
+export declare function pipeParsers<T>(p: Parser<T>): ParserPipeline<T>;
+export declare class ParserPipeline<T> {
+    readonly parser: Parser<T>;
+    constructor(parser: Parser<T>);
+    then<U>(nextParser: PartialParser<T, U>): ParserPipeline<U>;
+}

package/dist/parse-perseus-json/general-purpose-parsers/pipe-parsers.typetest.d.ts

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

package/dist/parse-perseus-json/general-purpose-parsers/record.d.ts

@@ -0,0 +1,2 @@
+import type { Parser } from "../parser-types";
+export declare function record<K extends string, V>(parseKey: Parser<K>, parseValue: Parser<V>): Parser<Record<K, V>>;

package/dist/parse-perseus-json/general-purpose-parsers/string-to-number.d.ts

@@ -0,0 +1,2 @@
+import type { PartialParser } from "../parser-types";
+export declare const stringToNumber: PartialParser<string | number, number>;

package/dist/parse-perseus-json/general-purpose-parsers/string.d.ts

@@ -0,0 +1,2 @@
+import type { Parser } from "../parser-types";
+export declare const string: Parser<string>;

package/dist/parse-perseus-json/general-purpose-parsers/test-helpers.d.ts

@@ -0,0 +1,8 @@
+import { ErrorTrackingParseContext } from "../error-tracking-parse-context";
+import type { Mismatch, ParsedValue, Parser } from "../parser-types";
+import type { Failure } from "../result";
+export declare function ctx(): ErrorTrackingParseContext;
+export declare const anyFailure: Failure<any>;
+export declare const anySuccess: import("../result").Success<any>;
+export declare function parseFailureWith(expected: Partial<Mismatch>): Failure<Mismatch[]>;
+export declare function summonParsedValue<P extends Parser<any>>(): ParsedValue<P>;

package/dist/parse-perseus-json/general-purpose-parsers/trio.d.ts

@@ -0,0 +1,2 @@
+import type { Parser } from "../parser-types";
+export declare function trio<A, B, C>(parseA: Parser<A>, parseB: Parser<B>, parseC: Parser<C>): Parser<[A, B, C]>;

package/dist/parse-perseus-json/general-purpose-parsers/union.d.ts

@@ -0,0 +1,7 @@
+import type { Parser } from "../parser-types";
+export declare function union<T>(parseBranch: Parser<T>): UnionBuilder<T>;
+export declare class UnionBuilder<T> {
+    parser: Parser<T>;
+    constructor(parser: Parser<T>);
+    or<New>(newBranch: Parser<New>): UnionBuilder<T | New>;
+}

package/dist/parse-perseus-json/general-purpose-parsers/union.typetest.d.ts

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

package/dist/parse-perseus-json/general-purpose-parsers/unknown.d.ts

@@ -0,0 +1,2 @@
+import type { Parser } from "../parser-types";
+export declare const unknown: Parser<unknown>;

package/dist/parse-perseus-json/index.d.ts

@@ -0,0 +1,45 @@
+import type { Result } from "./result";
+import type { PerseusItem, PerseusArticle } from "../data-schema";
+/**
+ * Helper to parse PerseusItem JSON
+ * Why not just use JSON.parse? We want:
+ * - To make sure types are correct
+ * - To give us a central place to validate/transform output if needed
+ * @deprecated - use parseAndMigratePerseusItem instead
+ * @param {string} json - the stringified PerseusItem JSON
+ * @returns {PerseusItem} the parsed PerseusItem object
+ */
+export declare function parsePerseusItem(json: string): PerseusItem;
+export type ParseFailureDetail = {
+    /**
+     * A human-readable error message describing where in the object tree
+     * parsing failed.
+     */
+    message: string;
+    /**
+     * The raw result of parsing the input JSON, with no migrations applied.
+     * Use at your own risk.
+     */
+    invalidObject: unknown;
+};
+/**
+ * Parses a PerseusItem from a JSON string, migrates old formats to the latest
+ * schema, and runtime-typechecks the result. Use this to parse assessmentItem
+ * data.
+ *
+ * @returns a {@link Result} of the parsed PerseusItem. If the result is a
+ * failure, it will contain an error message describing where in the tree
+ * parsing failed.
+ * @throws SyntaxError if the argument is not well-formed JSON.
+ */
+export declare function parseAndMigratePerseusItem(json: string): Result<PerseusItem, ParseFailureDetail>;
+/**
+ * Parses a PerseusArticle from a JSON string, migrates old formats to the
+ * latest schema, and runtime-typechecks the result.
+ *
+ * @returns a {@link Result} of the parsed PerseusArticle. If the result is a
+ * failure, it will contain an error message describing where in the tree
+ * parsing failed.
+ * @throws SyntaxError if the argument is not well-formed JSON.
+ */
+export declare function parseAndMigratePerseusArticle(json: string): Result<PerseusArticle, ParseFailureDetail>;

package/dist/parse-perseus-json/object-path.d.ts

@@ -0,0 +1,2 @@
+import type { PathSegment } from "./parser-types";
+export declare function formatPath(path: PathSegment[]): string;

package/dist/parse-perseus-json/parse-failure-detail.d.ts

@@ -0,0 +1,2 @@
+import type { Mismatch } from "./parser-types";
+export declare function message(failure: Mismatch): string;

package/dist/parse-perseus-json/parse.d.ts

@@ -0,0 +1,3 @@
+import type { Parser } from "./parser-types";
+import type { Result } from "./result";
+export declare function parse<T>(value: unknown, parser: Parser<T>): Result<T, string>;

package/dist/parse-perseus-json/parser-types.d.ts

@@ -0,0 +1,30 @@
+import type { Success, Failure, Result } from "./result";
+export type Parser<T> = (rawVal: unknown, ctx: ParseContext) => ParseResult<T>;
+export type PartialParser<Input, Output> = (rawVal: Input, ctx: ParseContext) => ParseResult<Output>;
+export type ParseResult<T> = Result<T, Mismatch[]>;
+export type Mismatch = {
+    expected: string[];
+    badValue: unknown;
+    path: PathSegment[];
+};
+export type PathSegment = keyof any;
+export interface ParseContext {
+    /**
+     * Returns a Success result based on the current state of the parse.
+     * @param value The value to return in the Success.
+     */
+    success<T>(value: T): Success<T>;
+    /**
+     * Returns a Failure result based on the current state of the parse.
+     *
+     * @param expected one or more descriptions of the types that were expected.
+     * An array of several expected types has "any" semantics - any of the
+     * listed types is valid.
+     * @param badValue the value that caused the parse to fail.
+     */
+    failure(expected: string | string[], badValue: unknown): Failure<Mismatch[]>;
+    forSubtree(key: PathSegment): ParseContext;
+}
+export type ParsedValue<P extends Parser<any>> = Extract<ReturnType<P>, {
+    type: "success";
+}>["value"];

package/dist/parse-perseus-json/perseus-parsers/categorizer-widget.d.ts

@@ -0,0 +1,3 @@
+import type { CategorizerWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseCategorizerWidget: Parser<CategorizerWidget>;

package/dist/parse-perseus-json/perseus-parsers/cs-program-widget.d.ts

@@ -0,0 +1,3 @@
+import type { CSProgramWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseCSProgramWidget: Parser<CSProgramWidget>;

package/dist/parse-perseus-json/perseus-parsers/definition-widget.d.ts

@@ -0,0 +1,3 @@
+import type { DefinitionWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseDefinitionWidget: Parser<DefinitionWidget>;

package/dist/parse-perseus-json/perseus-parsers/dropdown-widget.d.ts

@@ -0,0 +1,3 @@
+import type { DropdownWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseDropdownWidget: Parser<DropdownWidget>;

package/dist/parse-perseus-json/perseus-parsers/explanation-widget.d.ts

@@ -0,0 +1,3 @@
+import type { ExplanationWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseExplanationWidget: Parser<ExplanationWidget>;

package/dist/parse-perseus-json/perseus-parsers/expression-widget.d.ts

@@ -0,0 +1,3 @@
+import type { ExpressionWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseExpressionWidget: Parser<ExpressionWidget>;

package/dist/parse-perseus-json/perseus-parsers/graded-group-set-widget.d.ts

@@ -0,0 +1,3 @@
+import type { GradedGroupSetWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseGradedGroupSetWidget: Parser<GradedGroupSetWidget>;

package/dist/parse-perseus-json/perseus-parsers/graded-group-widget.d.ts

@@ -0,0 +1,16 @@
+import type { GradedGroupWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseGradedGroupWidgetOptions: Parser<{
+    title: string;
+    hasHint: boolean | null | undefined;
+    hint: import("../..").PerseusRenderer | null | undefined;
+    content: string;
+    widgets: import("../..").MakeWidgetMap<import("../..").PerseusWidgetTypes>;
+    widgetEnabled: boolean | null | undefined;
+    immutableWidgets: boolean | null | undefined;
+    images: Record<string, {
+        width: number;
+        height: number;
+    }>;
+}>;
+export declare const parseGradedGroupWidget: Parser<GradedGroupWidget>;

package/dist/parse-perseus-json/perseus-parsers/grapher-widget.d.ts

@@ -0,0 +1,3 @@
+import type { GrapherWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseGrapherWidget: Parser<GrapherWidget>;

package/dist/parse-perseus-json/perseus-parsers/group-widget.d.ts

@@ -0,0 +1,3 @@
+import type { GroupWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseGroupWidget: Parser<GroupWidget>;

package/dist/parse-perseus-json/perseus-parsers/hint.d.ts

@@ -0,0 +1,3 @@
+import type { Hint } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseHint: Parser<Hint>;

package/dist/parse-perseus-json/perseus-parsers/iframe-widget.d.ts

@@ -0,0 +1,3 @@
+import type { IFrameWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseIframeWidget: Parser<IFrameWidget>;

package/dist/parse-perseus-json/perseus-parsers/image-widget.d.ts

@@ -0,0 +1,3 @@
+import type { ImageWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseImageWidget: Parser<ImageWidget>;

package/dist/parse-perseus-json/perseus-parsers/images-map.d.ts

@@ -0,0 +1,5 @@
+import type { PerseusImageDetail } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseImages: Parser<{
+    [key: string]: PerseusImageDetail;
+}>;

package/dist/parse-perseus-json/perseus-parsers/input-number-widget.d.ts

@@ -0,0 +1,3 @@
+import type { InputNumberWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseInputNumberWidget: Parser<InputNumberWidget>;

package/dist/parse-perseus-json/perseus-parsers/interaction-widget.d.ts

@@ -0,0 +1,3 @@
+import type { InteractionWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseInteractionWidget: Parser<InteractionWidget>;

package/dist/parse-perseus-json/perseus-parsers/interactive-graph-widget.d.ts

@@ -0,0 +1,3 @@
+import type { InteractiveGraphWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseInteractiveGraphWidget: Parser<InteractiveGraphWidget>;

package/dist/parse-perseus-json/perseus-parsers/label-image-widget.d.ts

@@ -0,0 +1,3 @@
+import type { LabelImageWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseLabelImageWidget: Parser<LabelImageWidget>;

package/dist/parse-perseus-json/perseus-parsers/matcher-widget.d.ts

@@ -0,0 +1,3 @@
+import type { MatcherWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseMatcherWidget: Parser<MatcherWidget>;

package/dist/parse-perseus-json/perseus-parsers/matrix-widget.d.ts

@@ -0,0 +1,3 @@
+import type { MatrixWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseMatrixWidget: Parser<MatrixWidget>;

package/dist/parse-perseus-json/perseus-parsers/measurer-widget.d.ts

@@ -0,0 +1,3 @@
+import type { MeasurerWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseMeasurerWidget: Parser<MeasurerWidget>;

package/dist/parse-perseus-json/perseus-parsers/molecule-renderer-widget.d.ts

@@ -0,0 +1,3 @@
+import type { MoleculeRendererWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseMoleculeRendererWidget: Parser<MoleculeRendererWidget>;

package/dist/parse-perseus-json/perseus-parsers/number-line-widget.d.ts

@@ -0,0 +1,3 @@
+import type { NumberLineWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseNumberLineWidget: Parser<NumberLineWidget>;

package/dist/parse-perseus-json/perseus-parsers/numeric-input-widget.d.ts

@@ -0,0 +1,3 @@
+import type { NumericInputWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseNumericInputWidget: Parser<NumericInputWidget>;

package/dist/parse-perseus-json/perseus-parsers/orderer-widget.d.ts

@@ -0,0 +1,3 @@
+import type { OrdererWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseOrdererWidget: Parser<OrdererWidget>;

package/dist/parse-perseus-json/perseus-parsers/passage-ref-widget.d.ts

@@ -0,0 +1,3 @@
+import type { PassageRefWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parsePassageRefWidget: Parser<PassageRefWidget>;

package/dist/parse-perseus-json/perseus-parsers/passage-widget.d.ts

@@ -0,0 +1,3 @@
+import type { PassageWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parsePassageWidget: Parser<PassageWidget>;

package/dist/parse-perseus-json/perseus-parsers/perseus-article.d.ts

@@ -0,0 +1,3 @@
+import type { PerseusArticle } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parsePerseusArticle: Parser<PerseusArticle>;

package/dist/parse-perseus-json/perseus-parsers/perseus-image-background.d.ts

@@ -0,0 +1,3 @@
+import type { PerseusImageBackground } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parsePerseusImageBackground: Parser<PerseusImageBackground>;

package/dist/parse-perseus-json/perseus-parsers/perseus-item.d.ts

@@ -0,0 +1,3 @@
+import type { PerseusItem } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parsePerseusItem: Parser<PerseusItem>;

package/dist/parse-perseus-json/perseus-parsers/perseus-renderer.d.ts

@@ -0,0 +1,3 @@
+import type { PerseusRenderer } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parsePerseusRenderer: Parser<PerseusRenderer>;

package/dist/parse-perseus-json/perseus-parsers/phet-simulation-widget.d.ts

@@ -0,0 +1,3 @@
+import type { PhetSimulationWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parsePhetSimulationWidget: Parser<PhetSimulationWidget>;

package/dist/parse-perseus-json/perseus-parsers/plotter-widget.d.ts

@@ -0,0 +1,3 @@
+import type { PlotterWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parsePlotterWidget: Parser<PlotterWidget>;

package/dist/parse-perseus-json/perseus-parsers/python-program-widget.d.ts

@@ -0,0 +1,3 @@
+import type { PythonProgramWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parsePythonProgramWidget: Parser<PythonProgramWidget>;

package/dist/parse-perseus-json/perseus-parsers/radio-widget.d.ts

@@ -0,0 +1,3 @@
+import type { RadioWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseRadioWidget: Parser<RadioWidget>;

package/dist/parse-perseus-json/perseus-parsers/sorter-widget.d.ts

@@ -0,0 +1,3 @@
+import type { SorterWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseSorterWidget: Parser<SorterWidget>;

package/dist/parse-perseus-json/perseus-parsers/table-widget.d.ts

@@ -0,0 +1,3 @@
+import type { TableWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseTableWidget: Parser<TableWidget>;

package/dist/parse-perseus-json/perseus-parsers/versioned-widget-options.d.ts

@@ -0,0 +1,36 @@
+import type { Version } from "../../data-schema";
+import type { Parser } from "../parser-types";
+type Versioned = {
+    version?: Version;
+};
+/**
+ * Creates a parser for a widget options type with multiple major versions. Old
+ * versions are migrated to the latest version. The parse fails if the input
+ * data does not match any of the versions.
+ *
+ * @example
+ * const parseOptions = versionedWidgetOptions(3, parseOptionsV3)
+ *     .withMigrationFrom(2, parseOptionsV2, migrateV2ToV3)
+ *     .withMigrationFrom(1, parseOptionsV1, migrateV1ToV2)
+ *     .withMigrationFrom(0, parseOptionsV0, migrateV0ToV1)
+ *     .parser;
+ *
+ * @param latestMajorVersion the latest major version of the widget options.
+ * @param parseLatest a {@link Parser} for the latest version of the widget
+ * options.
+ * @returns a builder object, to which migrations from earlier versions can be
+ * added. Migrations must be added in "reverse chronological" order as in the
+ * example above.
+ */
+export declare function versionedWidgetOptions<Latest extends Versioned>(latestMajorVersion: number, parseLatest: Parser<Latest>): VersionedWidgetOptionsParserBuilder<Latest, Latest>;
+declare class VersionedWidgetOptionsParserBuilder<Latest extends Versioned, MigratableWidgetOptions extends Versioned> {
+    private migrateToLatest;
+    private parseOtherVersions;
+    parser: Parser<Latest>;
+    constructor(majorVersion: number, parseThisVersion: Parser<MigratableWidgetOptions>, migrateToLatest: (m: MigratableWidgetOptions) => Latest, parseOtherVersions: Parser<Latest>);
+    /**
+     * Add a migration from an old version of the widget options.
+     */
+    withMigrationFrom<Old extends Versioned>(majorVersion: number, parseOldVersion: Parser<Old>, migrateToNextVersion: (old: Old) => MigratableWidgetOptions): VersionedWidgetOptionsParserBuilder<Latest, Old>;
+}
+export {};

package/dist/parse-perseus-json/perseus-parsers/video-widget.d.ts

@@ -0,0 +1,3 @@
+import type { VideoWidget } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseVideoWidget: Parser<VideoWidget>;

package/dist/parse-perseus-json/perseus-parsers/widget.d.ts

@@ -0,0 +1,7 @@
+import type { WidgetOptions } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare function parseWidget<Type extends string, Options>(parseType: Parser<Type>, parseOptions: Parser<Options>): Parser<WidgetOptions<Type, Options>>;
+export declare function parseWidgetWithVersion<Version extends {
+    major: number;
+    minor: number;
+} | undefined, Type extends string, Options>(parseVersion: Parser<Version>, parseType: Parser<Type>, parseOptions: Parser<Options>): Parser<WidgetOptions<Type, Options>>;

package/dist/parse-perseus-json/perseus-parsers/widgets-map.d.ts

@@ -0,0 +1,3 @@
+import type { PerseusWidgetsMap } from "../../data-schema";
+import type { Parser } from "../parser-types";
+export declare const parseWidgetsMap: Parser<PerseusWidgetsMap>;

package/dist/parse-perseus-json/result.d.ts

@@ -0,0 +1,16 @@
+export type Result<S, F> = Success<S> | Failure<F>;
+export type Success<T> = {
+    type: "success";
+    value: T;
+};
+export type Failure<T> = {
+    type: "failure";
+    detail: T;
+};
+export declare function success<T>(value: T): Success<T>;
+export declare function failure<T>(detail: T): Failure<T>;
+export declare function isFailure<S, F>(result: Result<S, F>): result is Failure<F>;
+export declare function isSuccess<S, F>(result: Result<S, F>): result is Success<S>;
+export declare function assertFailure<S, F>(result: Result<S, F>): asserts result is Failure<F>;
+export declare function assertSuccess<S, F>(result: Result<S, F>): asserts result is Success<S>;
+export declare function all<S, F>(results: Array<Result<S, F>>, combineFailureDetails?: (a: F, b: F) => F): Result<S[], F>;

package/dist/utils/is-real-json-parse.d.ts

@@ -0,0 +1 @@
+export declare function isRealJSONParse(jsonParse: typeof JSON.parse): boolean;

package/dist/utils/widget-id-utils.d.ts

@@ -0,0 +1,38 @@
+import type { PerseusWidgetsMap } from "../data-schema";
+/**
+ * Add a widget placeholder using the widget ID.
+ * ex. addWidget("radio 1") => "[[☃ radio 1]]"
+ *
+ * @param {string} id
+ * @returns {string}
+ */
+export declare function addWidget(id: string): string;
+/**
+ * Regex for widget placeholders in a string.
+ *
+ * First capture group is the widget ID (ex. 'radio 1')
+ * Second capture group is the widget type (ex. "radio)
+ * exec return will look like: ['[[☃ radio 1]]', 'radio 1', 'radio']
+ */
+export declare function getWidgetRegex(): RegExp;
+/**
+ * Extract all widget IDs, which includes the widget type and instance number.
+ * example output: ['radio 1', 'categorizer 1', 'categorizor 2']
+ *
+ * Content should contain Perseus widget placeholders,
+ * which look like: '[[☃ radio 1]]'.
+ *
+ * @param {string} content
+ * @returns {ReadonlyArray<string>} widgetIds
+ */
+export declare function getWidgetIdsFromContent(content: string): ReadonlyArray<string>;
+/**
+ * Get a list of widget IDs from content,
+ * but only for specific widget types
+ *
+ * @param {string} type the type of widget (ie "radio")
+ * @param {string} content the string to parse
+ * @param {PerseusWidgetsMap} widgetMap widget ID to widget map
+ * @returns {ReadonlyArray<string>} the widget type (ie "radio")
+ */
+export declare function getWidgetIdsFromContentByType(type: string, content: string, widgetMap: PerseusWidgetsMap): ReadonlyArray<string>;