refkit-js 0.0.0 → 0.2.1

package/dist/document.js

@@ -0,0 +1,110 @@
+import { NativeDocument, NativeStyle, is_bundled_locale, } from "./wasm/refkit_js_native.js";
+import { assertInitialized } from "./runtime.js";
+import { callNative, readNative, MissingReferenceError } from "./errors.js";
+import { object, string } from "./inputs.js";
+import { Library, nativeLibrary } from "./library.js";
+import { Citation, citationsJson } from "./citation.js";
+const styles = new WeakMap();
+const styleSources = new WeakMap();
+export function setStyleSource(style, source) {
+    styleSources.set(style, source);
+}
+function nativeStyle(style) {
+    const native = styles.get(style);
+    if (!native)
+        throw new TypeError("style must be a Style");
+    return native;
+}
+export class Style {
+    constructor(native) {
+        styles.set(this, native);
+    }
+    static load(name) {
+        assertInitialized();
+        return new Style(callNative(() => NativeStyle.load(string(name, "name"))));
+    }
+    static fromXml(xml) {
+        assertInitialized();
+        return new Style(callNative(() => NativeStyle.from_xml(string(xml, "xml"))));
+    }
+    get id() {
+        const id = callNative(() => nativeStyle(this).id);
+        return styleSources.get(this) ?? id;
+    }
+    get title() {
+        return callNative(() => nativeStyle(this).title);
+    }
+}
+export class Locale {
+    code;
+    constructor(code) {
+        this.code = code;
+        Object.freeze(this);
+    }
+    static load(code) {
+        assertInitialized();
+        string(code, "code");
+        if (!callNative(() => is_bundled_locale(code)))
+            throw new RangeError(`unknown bundled locale ${JSON.stringify(code)}`);
+        return new Locale(code);
+    }
+}
+let renderedDocument;
+export class RenderedDocument {
+    citationOrder;
+    citations;
+    bibliography;
+    constructor(data) {
+        this.citationOrder = Object.freeze(data.citationOrder);
+        this.citations = Object.freeze(data.citations);
+        this.bibliography = data.bibliography;
+        Object.freeze(this);
+    }
+    static {
+        renderedDocument = (data) => new RenderedDocument(data);
+    }
+    get(id) {
+        string(id, "id");
+        if (!Object.hasOwn(this.citations, id))
+            throw new MissingReferenceError(`unknown citation id ${JSON.stringify(id)}`);
+        return this.citations[id];
+    }
+}
+export class Document {
+    #native;
+    constructor(library, style, options = {}) {
+        assertInitialized();
+        object(options, "options", ["locale"]);
+        const locale = options.locale instanceof Locale ? options.locale.code : options.locale;
+        if (locale != null)
+            string(locale, "locale");
+        this.#native = callNative(() => new NativeDocument(nativeLibrary(library), nativeStyle(style), locale ?? undefined));
+    }
+    render(citations) {
+        const input = citationsJson(citations);
+        return renderedDocument(readNative(() => this.#native.render(input)));
+    }
+    citedBibliography(citations) {
+        const input = citationsJson(citations);
+        return readNative(() => this.#native.cited_bibliography(input));
+    }
+    fullBibliography() {
+        return readNative(() => this.#native.full_bibliography());
+    }
+}
+function withDocument(library, options, render) {
+    object(options, "options", ["style", "locale"]);
+    const style = options.style instanceof Style
+        ? options.style
+        : Style.load(options.style === undefined ? "apa" : options.style);
+    const document = new Document(library, style, {
+        locale: options.locale === undefined ? "en-US" : options.locale,
+    });
+    return render(document);
+}
+export function cite(library, citation, options = {}) {
+    return withDocument(library, options, (document) => document.render([new Citation("citation", citation)]).get("citation"));
+}
+export function fullBibliography(library, options = {}) {
+    return withDocument(library, options, (document) => document.fullBibliography());
+}

package/dist/errors.d.ts

@@ -0,0 +1,30 @@
+import type { Diagnostic } from "./types.js";
+export declare class RefkitError extends Error {
+    readonly name: string;
+}
+export declare class ParseError extends RefkitError {
+    readonly name: string;
+    readonly diagnostics: readonly Diagnostic[];
+    constructor(message: string, diagnostics?: readonly Diagnostic[]);
+}
+export declare class MissingReferenceError extends RefkitError {
+    readonly name: string;
+}
+export declare class TidyError extends RefkitError {
+    readonly name: string;
+}
+export declare class TidySyntaxError extends TidyError {
+    readonly name: string;
+    readonly line: number;
+    readonly column: number;
+    readonly byte: number;
+    readonly character: string | null;
+    constructor(message: string, syntax: {
+        line: number;
+        column: number;
+        byte: number;
+        character: string | null;
+    });
+}
+export declare function callNative<T>(operation: () => T): T;
+export declare function readNative<T>(operation: () => string): T;

package/dist/errors.js

@@ -0,0 +1,73 @@
+export class RefkitError extends Error {
+    name = "RefkitError";
+}
+export class ParseError extends RefkitError {
+    name = "ParseError";
+    diagnostics;
+    constructor(message, diagnostics = []) {
+        super(message);
+        this.diagnostics = diagnostics;
+    }
+}
+export class MissingReferenceError extends RefkitError {
+    name = "MissingReferenceError";
+}
+export class TidyError extends RefkitError {
+    name = "TidyError";
+}
+export class TidySyntaxError extends TidyError {
+    name = "TidySyntaxError";
+    line;
+    column;
+    byte;
+    character;
+    constructor(message, syntax) {
+        super(message);
+        this.line = syntax.line;
+        this.column = syntax.column;
+        this.byte = syntax.byte;
+        this.character = syntax.character;
+    }
+}
+function convertError(error) {
+    if (error instanceof Error)
+        return error;
+    let value;
+    try {
+        value = JSON.parse(String(error));
+        if (typeof value?.message !== "string")
+            return new RefkitError(String(error));
+    }
+    catch {
+        return new RefkitError(String(error));
+    }
+    switch (value.name) {
+        case "ParseError":
+            return new ParseError(value.message, value.diagnostics);
+        case "MissingReferenceError":
+            return new MissingReferenceError(value.message);
+        case "TidySyntaxError":
+            if (value.syntax)
+                return new TidySyntaxError(value.message, value.syntax);
+            return new TidyError(value.message);
+        case "TidyError":
+            return new TidyError(value.message);
+        case "TypeError":
+            return new TypeError(value.message);
+        case "RangeError":
+            return new RangeError(value.message);
+        default:
+            return new RefkitError(value.message);
+    }
+}
+export function callNative(operation) {
+    try {
+        return operation();
+    }
+    catch (error) {
+        throw convertError(error);
+    }
+}
+export function readNative(operation) {
+    return JSON.parse(callNative(operation));
+}

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { init, getBuildInfo, type BuildInfo, type InitOptions, } from "./runtime.js";
+export { version } from "./wasm/version.js";
+export { RefkitError, ParseError, MissingReferenceError, TidyError, TidySyntaxError, } from "./errors.js";
+export { Library, type ParseOptions, type ProjectOptions } from "./library.js";
+export { Cite, CitationGroup, Citation, type CiteOptions, type CitationOptions, type CitationInput, } from "./citation.js";
+export { Style, Locale, Document, RenderedDocument, cite, fullBibliography, type DocumentOptions, type RenderOptions, } from "./document.js";
+export { BibDocument, BibEntryMap, BibEntry, BibFieldMap, BibField, } from "./raw.js";
+export { tidyBibtex, type TidySettings } from "./tidy.js";
+export type * from "./types.js";

package/dist/index.js

@@ -0,0 +1,8 @@
+export { init, getBuildInfo, } from "./runtime.js";
+export { version } from "./wasm/version.js";
+export { RefkitError, ParseError, MissingReferenceError, TidyError, TidySyntaxError, } from "./errors.js";
+export { Library } from "./library.js";
+export { Cite, CitationGroup, Citation, } from "./citation.js";
+export { Style, Locale, Document, RenderedDocument, cite, fullBibliography, } from "./document.js";
+export { BibDocument, BibEntryMap, BibEntry, BibFieldMap, BibField, } from "./raw.js";
+export { tidyBibtex } from "./tidy.js";

package/dist/inputs.d.ts

@@ -0,0 +1,5 @@
+export declare function string(value: unknown, name: string): string;
+export declare function optionalString(value: unknown, name: string): string | null;
+export declare function iterable<T>(value: Iterable<T>, name: string): T[];
+export declare function strings(value: Iterable<string>, name: string): string[];
+export declare function object(value: unknown, name: string, allowed?: readonly string[]): void;

package/dist/inputs.js

@@ -0,0 +1,34 @@
+export function string(value, name) {
+    if (typeof value !== "string")
+        throw new TypeError(`${name} must be a string`);
+    return value;
+}
+export function optionalString(value, name) {
+    return value == null ? null : string(value, name);
+}
+export function iterable(value, name) {
+    if (typeof value === "string" ||
+        value == null ||
+        typeof value[Symbol.iterator] !== "function") {
+        throw new TypeError(`${name} must be an iterable of items`);
+    }
+    return Array.from(value);
+}
+export function strings(value, name) {
+    return iterable(value, name).map((item) => string(item, name));
+}
+export function object(value, name, allowed) {
+    if (value == null ||
+        typeof value !== "object" ||
+        Array.isArray(value) ||
+        ![Object.prototype, null].includes(Object.getPrototypeOf(value))) {
+        throw new TypeError(`${name} must be an options object`);
+    }
+    if (allowed) {
+        for (const key of Reflect.ownKeys(value)) {
+            if (typeof key !== "string" || !allowed.includes(key)) {
+                throw new TypeError(`unknown ${name} field ${String(key)}`);
+            }
+        }
+    }
+}

package/dist/library.d.ts

@@ -0,0 +1,26 @@
+import { NativeLibrary } from "./wasm/refkit_js_native.js";
+import type { Diagnostic, Entry, ProjectionField, ProjectionRow, RecoveryPolicy } from "./types.js";
+export interface ParseOptions {
+    recovery?: RecoveryPolicy;
+}
+export interface ProjectOptions {
+    keys?: Iterable<string> | null;
+}
+export declare function nativeLibrary(library: Library): NativeLibrary;
+export declare function setLibraryDecodingDiagnostic(library: Library, diagnostic: Diagnostic | null): void;
+export declare class Library implements Iterable<Entry> {
+    private constructor();
+    static parseBibtex(source: string, options?: ParseOptions): Library;
+    static parseYaml(source: string): Library;
+    get diagnostics(): readonly Diagnostic[];
+    get size(): number;
+    keys(): string[];
+    values(): Entry[];
+    get(key: string): Entry | null;
+    getMany(keys: Iterable<string>): Entry[];
+    has(key: string): boolean;
+    isEmpty(): boolean;
+    select(selector: string): Entry[];
+    project(fields?: Iterable<ProjectionField> | null, options?: ProjectOptions): ProjectionRow[];
+    [Symbol.iterator](): Iterator<Entry>;
+}

package/dist/library.js

@@ -0,0 +1,69 @@
+import { NativeLibrary } from "./wasm/refkit_js_native.js";
+import { assertInitialized } from "./runtime.js";
+import { callNative, readNative } from "./errors.js";
+import { object, string, strings } from "./inputs.js";
+const libraries = new WeakMap();
+const sourceDiagnostics = new WeakMap();
+export function nativeLibrary(library) {
+    const native = libraries.get(library);
+    if (!native)
+        throw new TypeError("library must be a Library");
+    return native;
+}
+export function setLibraryDecodingDiagnostic(library, diagnostic) {
+    sourceDiagnostics.set(library, diagnostic ? [diagnostic] : []);
+}
+export class Library {
+    constructor(native) {
+        libraries.set(this, native);
+    }
+    static parseBibtex(source, options = {}) {
+        assertInitialized();
+        object(options, "options", ["recovery"]);
+        return new Library(callNative(() => NativeLibrary.parse_bibtex(string(source, "source"), string(options.recovery === undefined ? "error" : options.recovery, "recovery"))));
+    }
+    static parseYaml(source) {
+        assertInitialized();
+        return new Library(callNative(() => NativeLibrary.parse_yaml(string(source, "source"))));
+    }
+    get diagnostics() {
+        return [
+            ...structuredClone(sourceDiagnostics.get(this) ?? []),
+            ...readNative(() => nativeLibrary(this).diagnostics()),
+        ];
+    }
+    get size() {
+        return callNative(() => nativeLibrary(this).size);
+    }
+    keys() {
+        return readNative(() => nativeLibrary(this).keys());
+    }
+    values() {
+        return readNative(() => nativeLibrary(this).records());
+    }
+    get(key) {
+        return readNative(() => nativeLibrary(this).get_record(string(key, "key")));
+    }
+    getMany(keys) {
+        const input = JSON.stringify(strings(keys, "keys"));
+        return readNative(() => nativeLibrary(this).get_many(input));
+    }
+    has(key) {
+        return this.get(key) !== null;
+    }
+    isEmpty() {
+        return this.size === 0;
+    }
+    select(selector) {
+        return readNative(() => nativeLibrary(this).select_records(string(selector, "selector")));
+    }
+    project(fields, options = {}) {
+        object(options, "options", ["keys"]);
+        const fieldsJson = JSON.stringify(fields == null ? null : strings(fields, "fields"));
+        const keysJson = JSON.stringify(options.keys == null ? null : strings(options.keys, "keys"));
+        return readNative(() => nativeLibrary(this).project(fieldsJson, keysJson));
+    }
+    [Symbol.iterator]() {
+        return this.values()[Symbol.iterator]();
+    }
+}

package/dist/node.d.ts

@@ -0,0 +1,14 @@
+import { Library, type ParseOptions } from "./library.js";
+import { Style } from "./document.js";
+import { BibDocument } from "./raw.js";
+import type { TidySettings } from "./tidy.js";
+import type { TidyResult } from "./types.js";
+export * from "./index.js";
+export type FilePath = string | URL;
+export interface TidyFileSettings extends TidySettings {
+    output?: FilePath | null;
+}
+export declare function readLibrary(path: FilePath, options?: ParseOptions): Promise<Library>;
+export declare function readBibDocument(path: FilePath): Promise<BibDocument>;
+export declare function readStyle(path: FilePath): Promise<Style>;
+export declare function tidyFile(path: FilePath, settings?: TidyFileSettings): Promise<TidyResult>;

package/dist/node.js

@@ -0,0 +1,89 @@
+import { readFileSync } from "node:fs";
+import { readFile, writeFile } from "node:fs/promises";
+import { extname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { decode_bibliography } from "./wasm/refkit_js_native.js";
+import { initializeSync } from "./runtime.js";
+import { readNative, RefkitError } from "./errors.js";
+import { object, string } from "./inputs.js";
+import { Library, setLibraryDecodingDiagnostic, } from "./library.js";
+import { Style, setStyleSource } from "./document.js";
+import { BibDocument, setBibDecodingDiagnostic } from "./raw.js";
+initializeSync(readFileSync(new URL("./wasm/refkit_js_native_bg.wasm", import.meta.url)));
+export * from "./index.js";
+function filePath(path) {
+    if (path instanceof URL)
+        return fileURLToPath(path);
+    if (typeof path !== "string")
+        throw new TypeError("path must be a string or file URL");
+    return path;
+}
+async function readBytes(path) {
+    const name = filePath(path);
+    try {
+        return await readFile(name);
+    }
+    catch (cause) {
+        throw new RefkitError(`failed to read ${name}: ${String(cause)}`, {
+            cause,
+        });
+    }
+}
+async function readBibliography(path) {
+    const bytes = await readBytes(path);
+    return readNative(() => decode_bibliography(bytes));
+}
+export async function readLibrary(path, options = {}) {
+    object(options, "options", ["recovery"]);
+    const recovery = string(options.recovery === undefined ? "error" : options.recovery, "recovery");
+    if (recovery !== "error" && recovery !== "report")
+        throw new RangeError("recovery must be 'error' or 'report'");
+    const extension = extname(filePath(path)).toLowerCase();
+    if (![".bib", ".yaml", ".yml"].includes(extension)) {
+        throw new RefkitError(extension
+            ? `unsupported bibliography extension ${JSON.stringify(extension.slice(1))}`
+            : "bibliography path has no extension");
+    }
+    const source = await readBibliography(path);
+    const library = extension === ".bib"
+        ? Library.parseBibtex(source.text, { recovery })
+        : Library.parseYaml(source.text);
+    setLibraryDecodingDiagnostic(library, source.diagnostic);
+    return library;
+}
+export async function readBibDocument(path) {
+    const source = await readBibliography(path);
+    const document = BibDocument.parse(source.text);
+    setBibDecodingDiagnostic(document, source.diagnostic);
+    return document;
+}
+export async function readStyle(path) {
+    const bytes = await readBytes(path);
+    let xml;
+    try {
+        xml = new TextDecoder("utf-8", { fatal: true }).decode(bytes);
+    }
+    catch (cause) {
+        throw new RefkitError(`failed to read style ${filePath(path)} as UTF-8`, {
+            cause,
+        });
+    }
+    const style = Style.fromXml(xml);
+    setStyleSource(style, filePath(path));
+    return style;
+}
+export async function tidyFile(path, settings = {}) {
+    object(settings, "settings", ["options", "output"]);
+    const output = settings.output == null ? null : filePath(settings.output);
+    const document = await readBibDocument(path);
+    const result = document.tidy({ options: settings.options ?? null });
+    if (output !== null) {
+        try {
+            await writeFile(output, result.bibtex, "utf8");
+        }
+        catch (cause) {
+            throw new RefkitError(`failed to write BibTeX ${output}: ${String(cause)}`, { cause });
+        }
+    }
+    return result;
+}

package/dist/raw.d.ts

@@ -0,0 +1,59 @@
+import { type TidySettings } from "./tidy.js";
+import type { Diagnostic, RawBlock, RawFailedBlock, RawSpan, TidyResult } from "./types.js";
+export declare function setBibDecodingDiagnostic(document: BibDocument, diagnostic: Diagnostic | null): void;
+export declare class BibDocument {
+    #private;
+    private constructor();
+    static parse(source: string): BibDocument;
+    get entries(): BibEntryMap;
+    get diagnostics(): readonly Diagnostic[];
+    get comments(): string[];
+    get preamble(): string;
+    get strings(): Record<string, string>;
+    get failedBlocks(): RawFailedBlock[];
+    get blocks(): RawBlock[];
+    toBibtex(): string;
+    tidy(settings?: TidySettings): TidyResult;
+}
+export declare class BibEntryMap implements Iterable<BibEntry> {
+    #private;
+    private constructor();
+    uniqueKeys(): string[];
+    occurrenceKeys(): string[];
+    occurrences(): BibEntry[];
+    getAll(key: string): BibEntry[];
+    getUnique(key: string): BibEntry | null;
+    get size(): number;
+    isEmpty(): boolean;
+    has(key: string): boolean;
+    [Symbol.iterator](): Iterator<BibEntry>;
+}
+export declare class BibEntry {
+    #private;
+    private constructor();
+    get key(): string;
+    get kind(): string;
+    get span(): RawSpan;
+    get fields(): BibFieldMap;
+}
+export declare class BibFieldMap implements Iterable<BibField> {
+    #private;
+    private constructor();
+    uniqueKeys(): string[];
+    occurrenceKeys(): string[];
+    occurrences(): BibField[];
+    getAll(key: string): BibField[];
+    getUnique(key: string): BibField | null;
+    get size(): number;
+    isEmpty(): boolean;
+    has(key: string): boolean;
+    [Symbol.iterator](): Iterator<BibField>;
+}
+export declare class BibField {
+    #private;
+    private constructor();
+    get name(): string;
+    get span(): RawSpan;
+    get value(): string;
+    set value(value: string);
+}