mathjslab/lib/types/SourceResolver.d.ts

MathJSLab - An interpreter with language syntax like MATLAB®/Octave, ISBN 978-65-00-82338-7.

/**
 * Browser-friendly virtual source resolution for MATLAB/Octave-like `.m`
 * files.
 *
 * The interpreter remains synchronous, so network-backed resolvers prefetch
 * their manifest entries and then expose a synchronous lookup interface.
 */
/**
 * Kind of MATLAB/Octave-like source requested by the interpreter.
 */
type SourceKind = 'function' | 'script' | 'class';
/**
 * Host-provided source entry.
 */
type SourceEntry = {
    /** Optional canonical function, script, or class name. */
    name?: string;
    /**
     * Optional virtual source identity used by introspection.
     *
     * Browser hosts can set this to a manifest path or URL-like name. It is
     * intentionally separate from `name`, which remains the canonical language
     * lookup symbol.
     */
    sourceName?: string;
    /** Source text containing the `.m` file contents. */
    source: string;
};
/**
 * Callback used to provide source for a canonical name.
 */
type SourceProvider = (name: string) => string | SourceEntry | undefined;
/**
 * Source table keyed by canonical name.
 */
type SourceTable = Record<string, string | SourceEntry>;
/**
 * Resolver used by the interpreter for all external `.m` source kinds.
 */
interface SourceResolver {
    /**
     * Resolve one source entry by language kind and canonical name.
     *
     * @param kind Requested source kind.
     * @param name Canonical function, script, or class name.
     * @returns Source entry, if available.
     */
    resolve(kind: SourceKind, name: string): SourceEntry | undefined;
    /**
     * Test whether a virtual source directory is known.
     *
     * Browser hosts cannot expose arbitrary filesystem traversal, but source
     * tables and prefetched manifests still define stable virtual directories
     * such as `+pkg`, `scripts`, or URL-like folders.
     *
     * @param name Directory name or package-style path.
     * @returns `true` when a known source path is contained by that directory.
     */
    hasDirectory(name: string): boolean;
}
/**
 * Per-kind source tables/providers accepted by the default resolver.
 */
type SourceResolverConfig = {
    /** Host-provided function-file source strings. */
    functionSourceTable?: SourceTable;
    /** Lazy host-provided function-file source callback. */
    functionSourceProvider?: SourceProvider;
    /** Host-provided script-file source strings. */
    scriptSourceTable?: SourceTable;
    /** Lazy host-provided script-file source callback. */
    scriptSourceProvider?: SourceProvider;
    /** Host-provided class source strings. */
    classSourceTable?: SourceTable;
    /** Lazy host-provided class source callback. */
    classSourceProvider?: SourceProvider;
};
/**
 * Manifest entry describing one fetchable `.m` source file.
 */
type MFileManifestEntry = string | {
    /** Path relative to the resolver base URL. */
    path: string;
    /** Optional canonical function, script, or class name. */
    name?: string;
    /** Optional virtual `.m` identity used for lookup metadata. */
    sourceName?: string;
    /** Optional language kind. When omitted, the source is indexed for all kinds. */
    kind?: SourceKind;
};
/**
 * Manifest accepted by the fetch-backed resolver factory.
 */
type MFileManifest = {
    /** Base URL used for relative manifest paths. */
    baseUrl?: string;
    /** Fetchable `.m` file entries. */
    files: MFileManifestEntry[];
};
/**
 * Minimal fetch function shape used to keep this module independent from DOM
 * lib declarations in Node-oriented type builds.
 */
type SourceFetch = (input: string) => Promise<{
    ok?: boolean;
    status?: number;
    statusText?: string;
    text(): Promise<string>;
}>;
/**
 * Default synchronous resolver that preserves the existing table/provider
 * contract while making the interpreter depend on one common source API.
 */
declare class TableSourceResolver implements SourceResolver {
    private readonly config;
    /**
     * Create a table/provider resolver.
     *
     * @param config Source tables and providers grouped by source kind.
     */
    private constructor();
    /**
     * Create a resolver from source tables and providers.
     *
     * @param config Source resolver configuration.
     * @returns Resolver instance.
     */
    static readonly create: (config?: SourceResolverConfig) => TableSourceResolver;
    /**
     * Resolve one source entry.
     *
     * @param kind Requested source kind.
     * @param name Canonical name.
     * @returns Source entry, if available.
     */
    resolve(kind: SourceKind, name: string): SourceEntry | undefined;
    /**
     * Test whether any configured source table contains a virtual directory.
     *
     * Lazy providers cannot be enumerated synchronously, so only eager table
     * entries participate in directory discovery.
     */
    hasDirectory(name: string): boolean;
}
/**
 * In-memory resolver built from fetchable manifest entries.
 */
declare class ManifestSourceResolver implements SourceResolver {
    private readonly sources;
    /**
     * Create a manifest-backed resolver.
     *
     * @param sources Prefetched source entries grouped by kind.
     */
    private constructor();
    /**
     * Create a resolver from an already loaded source table.
     *
     * This is useful for tests and hosts that bundle source text eagerly. The
     * table is indexed for all source kinds because a `.m` file can represent a
     * function, script, or class until the parser inspects its contents.
     *
     * @param entries Loaded source entries keyed by canonical name.
     * @returns Resolver instance.
     */
    static readonly fromTable: (entries: SourceTable) => ManifestSourceResolver;
    /**
     * Load a browser manifest with `fetch` and return a synchronous resolver.
     *
     * @param manifest Manifest listing fetchable `.m` files.
     * @param fetcher Fetch implementation. Defaults to `globalThis.fetch`.
     * @returns Prefetched resolver.
     */
    static readonly fromManifest: (manifest: MFileManifest, fetcher?: SourceFetch) => Promise<ManifestSourceResolver>;
    /**
     * Resolve one prefetched manifest entry.
     *
     * @param kind Requested source kind.
     * @param name Canonical name.
     * @returns Source entry, if available.
     */
    resolve(kind: SourceKind, name: string): SourceEntry | undefined;
    /** Test whether the prefetched manifest contains a virtual directory. */
    hasDirectory(name: string): boolean;
}
export type { MFileManifest, MFileManifestEntry, SourceEntry, SourceFetch, SourceKind, SourceProvider, SourceResolver, SourceResolverConfig, SourceTable };
export { ManifestSourceResolver, TableSourceResolver };
declare const _default: {
    ManifestSourceResolver: typeof ManifestSourceResolver;
    TableSourceResolver: typeof TableSourceResolver;
};
export default _default;