@json-to-office/shared 1.2.0 → 1.3.0

package/dist/capabilities-DrHJ6_4G.d.ts

@@ -0,0 +1,210 @@
+/**
+ * Format-independent renderer contracts.
+ *
+ * This module deliberately knows nothing about DOCX or PPTX semantics. Each
+ * format owns its own intermediate representation (`DocxIR`, `PptxIR`) and its
+ * own feature union; the only thing shared between them is the shape of the
+ * contract a backend adapter must satisfy.
+ *
+ * Do not add format-specific feature names, IR nodes or units here.
+ */
+/** The Office formats this repository can produce. */
+type OfficeFormat = 'docx' | 'pptx';
+/**
+ * Options every renderer accepts.
+ *
+ * `deterministic` asks the adapter (and the packaging step after it) to make
+ * output byte-stable across runs: fixed zip entry timestamps, fixed core
+ * metadata timestamps, no random identifiers.
+ *
+ * `generatedAt` pins the timestamp written into package metadata. Callers that
+ * want reproducible bytes pass both.
+ */
+interface RenderOptions {
+    deterministic?: boolean;
+    generatedAt?: Date;
+}
+/**
+ * A backend that turns a format-specific IR into package bytes.
+ *
+ * @typeParam TIR - the format's intermediate representation (plain data)
+ * @typeParam TFeature - the format's feature union (see `capabilities.ts`)
+ * @typeParam TId - the string-literal union of renderer ids for the format
+ */
+interface OfficeRenderer<TIR, TFeature extends string, TId extends string> {
+    readonly id: TId;
+    readonly format: OfficeFormat;
+    readonly capabilities: ReadonlySet<TFeature>;
+    render(document: TIR, options?: RenderOptions): Promise<Uint8Array>;
+}
+/**
+ * Exhaustiveness guard for discriminated-union switches.
+ *
+ * Reaching this at runtime means an IR node kind was added without a matching
+ * `case`, so it throws rather than silently dropping content.
+ */
+declare function assertNever(value: never, context?: string): never;
+
+/**
+ * Diagnostics raised when an IR asks a renderer for something it cannot do.
+ *
+ * These are distinct from `GenerationWarning` (see `../types/warnings`), which
+ * describes authoring problems found while building the document. A renderer
+ * diagnostic describes a *backend* limitation: the document is fine, this
+ * particular adapter just cannot express part of it.
+ */
+type RendererDiagnosticSeverity = 'error' | 'warning';
+/**
+ * One unsupported (or degraded) feature at one place in the IR.
+ *
+ * `path` is an IR path such as `slides[2].elements[0].fill` — not an author-JSON
+ * path — because the check runs against compiled IR. Compilers record the
+ * authoring path alongside where it is useful for the message text.
+ */
+interface RendererDiagnostic<TFeature extends string = string> {
+    feature: TFeature;
+    path: string;
+    severity: RendererDiagnosticSeverity;
+    message: string;
+}
+interface UnsupportedRendererFeatureErrorInit<TFeature extends string = string> {
+    format: OfficeFormat;
+    rendererId: string;
+    diagnostics: readonly RendererDiagnostic<TFeature>[];
+}
+/**
+ * Aggregated failure thrown *before* rendering starts.
+ *
+ * One error carries every unsupported feature found in the IR so a caller sees
+ * the whole gap at once instead of fixing them one render at a time.
+ */
+declare class UnsupportedRendererFeatureError<TFeature extends string = string> extends Error {
+    readonly code = "UNSUPPORTED_RENDERER_FEATURE";
+    readonly format: OfficeFormat;
+    readonly rendererId: string;
+    /** Distinct unsupported features, in first-seen order. */
+    readonly features: readonly TFeature[];
+    /** Distinct IR paths that required them, in first-seen order. */
+    readonly paths: readonly string[];
+    /** Every error-severity diagnostic that produced this failure. */
+    readonly diagnostics: readonly RendererDiagnostic<TFeature>[];
+    constructor(init: UnsupportedRendererFeatureErrorInit<TFeature>);
+}
+/**
+ * A renderer id that is not registered for the format asked for.
+ *
+ * Caller input, not an infrastructure failure — which is the whole reason it is
+ * a class with a `code` rather than a bare `Error`. A server matching on the
+ * message text could only answer `500`, so an unknown id looked like the
+ * service falling over, and a retry looked worth attempting (#263).
+ */
+declare class UnknownRendererError extends Error {
+    readonly code = "UNKNOWN_RENDERER";
+    readonly format: OfficeFormat;
+    /** What the caller asked for. */
+    readonly rendererId: string;
+    /** Every id registered for this format, in registration order. */
+    readonly availableIds: readonly string[];
+    constructor(format: OfficeFormat, rendererId: string, availableIds: readonly string[]);
+}
+/** Build a `RendererDiagnostic` with `severity: 'error'`. */
+declare function rendererError<TFeature extends string>(feature: TFeature, path: string, message: string): RendererDiagnostic<TFeature>;
+/** Build a `RendererDiagnostic` with `severity: 'warning'`. */
+declare function rendererWarning<TFeature extends string>(feature: TFeature, path: string, message: string): RendererDiagnostic<TFeature>;
+/** Split diagnostics into blocking errors and non-blocking warnings. */
+declare function partitionDiagnostics<TFeature extends string>(diagnostics: readonly RendererDiagnostic<TFeature>[]): {
+    errors: RendererDiagnostic<TFeature>[];
+    warnings: RendererDiagnostic<TFeature>[];
+};
+
+/**
+ * Capability checking: what an IR *requires* versus what an adapter *provides*.
+ *
+ * A compiler records one `FeatureRequirement` each time it emits an IR node that
+ * needs a backend capability. Before rendering, `assertRendererSupports` diffs
+ * those requirements against the adapter's `capabilities` set and throws a
+ * single aggregated `UnsupportedRendererFeatureError` if anything is missing.
+ *
+ * The point is that nothing is dropped silently: a feature either appears in the
+ * adapter's capability set and is rendered, or it fails loudly before bytes are
+ * produced.
+ */
+/** One capability an IR node needs, and where in the IR it was needed. */
+interface FeatureRequirement<TFeature extends string = string> {
+    feature: TFeature;
+    /** IR path, e.g. `sections[0].children[3].image`. */
+    path: string;
+    /** Optional detail folded into the failure message. */
+    detail?: string;
+}
+/**
+ * Accumulates feature requirements during compilation.
+ *
+ * Deliberately per-compilation (never module-global) so concurrent generations
+ * never share state.
+ */
+declare class FeatureRequirementCollector<TFeature extends string> {
+    private readonly requirements;
+    private readonly seen;
+    /**
+     * Record that `feature` is needed at `path`.
+     *
+     * Duplicate (feature, path) pairs collapse, so a compiler can call this
+     * unconditionally inside a loop without inflating the diagnostics.
+     */
+    require(feature: TFeature, path: string, detail?: string): void;
+    /** Every recorded requirement, in first-seen order. */
+    list(): readonly FeatureRequirement<TFeature>[];
+    /** Distinct required features, in first-seen order. */
+    features(): readonly TFeature[];
+    /** True when nothing has been required yet. */
+    isEmpty(): boolean;
+}
+/**
+ * Diff required features against a capability set.
+ *
+ * Returns one error-severity diagnostic per unsupported requirement. An empty
+ * array means the renderer can render the IR.
+ */
+declare function diagnoseUnsupportedFeatures<TFeature extends string>(required: readonly FeatureRequirement<TFeature>[], capabilities: ReadonlySet<TFeature>, rendererId: string): RendererDiagnostic<TFeature>[];
+/**
+ * Throw one aggregated error if the renderer is missing any required feature.
+ *
+ * Call this after compiling to IR and before handing the IR to an adapter.
+ */
+declare function assertRendererSupports<TFeature extends string>(required: readonly FeatureRequirement<TFeature>[], renderer: Pick<OfficeRenderer<unknown, TFeature, string>, 'id' | 'format' | 'capabilities'>): void;
+/**
+ * A registry of renderers for a single format.
+ *
+ * Instances are created per format module, not per generation, and hold only
+ * immutable adapter descriptors — never per-document state.
+ */
+declare class RendererRegistry<TIR, TFeature extends string, TId extends string> {
+    private readonly format;
+    private readonly defaultId;
+    private readonly renderers;
+    constructor(format: OfficeFormat, defaultId: TId);
+    /**
+     * Register a lazily-constructed renderer.
+     *
+     * The factory is async and only invoked on selection, so an adapter whose
+     * backend is an optional dependency is never imported unless it is chosen.
+     */
+    register(id: TId, factory: () => Promise<OfficeRenderer<TIR, TFeature, TId>>): void;
+    /** Renderer ids registered for this format, in registration order. */
+    ids(): readonly TId[];
+    /** The id used when a caller does not pass one. */
+    getDefaultId(): TId;
+    has(id: string): id is TId;
+    /**
+     * Resolve a renderer, defaulting when `id` is omitted.
+     *
+     * An unknown id is `UnknownRendererError`, which carries the id asked for and
+     * the ones that exist, so a caller boundary can answer "bad request" rather
+     * than "the server broke". A missing optional dependency is re-thrown with an
+     * actionable install hint.
+     */
+    resolve(id?: TId): Promise<OfficeRenderer<TIR, TFeature, TId>>;
+}
+
+export { type FeatureRequirement as F, type OfficeFormat as O, type RenderOptions as R, UnknownRendererError as U, FeatureRequirementCollector as a, type OfficeRenderer as b, type RendererDiagnostic as c, type RendererDiagnosticSeverity as d, RendererRegistry as e, UnsupportedRendererFeatureError as f, type UnsupportedRendererFeatureErrorInit as g, assertNever as h, assertRendererSupports as i, diagnoseUnsupportedFeatures as j, rendererWarning as k, partitionDiagnostics as p, rendererError as r };