@rohal12/twee-ts 1.18.2 → 2.0.0

package/dist/types-BvI6pg2y.d.cts

@@ -0,0 +1,389 @@
+
+//#region src/types.d.ts
+/**
+ * All public interfaces for twee-ts.
+ */
+type OutputMode = 'html' | 'twee3' | 'twee1' | 'twine2-archive' | 'twine1-archive' | 'json';
+type WordCountMethod = 'tweego' | 'whitespace';
+interface InlineSource {
+  filename: string;
+  content: string | Buffer;
+}
+type SourceInput = string | InlineSource;
+/** A glob that leaves out the files below a folder, with the folder kept apart from the glob. */
+interface ExcludeGlob {
+  /** A folder (relative to the working directory, or absolute), read literally, never as a glob. */
+  readonly base: string;
+  /** The glob, matched against the file's path below `base`. */
+  readonly glob: string;
+}
+/**
+ * The options of `compile()` and the functions built on it. Only `sources` is required; an optional
+ * property set to `undefined` means the same as leaving it out.
+ *
+ * - `formatId` and `startPassage` win over StoryData's `format`/`format-version` and `start`; without
+ *   either, the default is 'sugarcube-2' and 'Start'. A `formatId` that is a local folder name uses
+ *   that folder as it is, so it keeps a stable format when a newer prerelease is installed; an exact
+ *   `format-version` in StoryData does not, because name requests see only the greatest local
+ *   version of each name and major version.
+ * - `formatUrls` and `formatIndices` take absolute `http:`/`https:` URLs. The local formats are
+ *   consulted first, then each format URL (requested again, conditionally, on every online build),
+ *   then each index, then the Story Formats Archive. A download is cached for the URL or index it
+ *   came from, and `noRemote` builds still use those cached downloads.
+ * - A missing or unreadable `headFile` is a TweeTsError (`INPUT_UNAVAILABLE`); an option of the wrong type,
+ *   an empty string or a negative `formatFetchTimeout` one with `INVALID_OPTIONS`, before anything is read.
+ */
+interface CompileOptions {
+  /**
+   * Files, directories, or inline sources to compile. Directories are walked
+   * recursively; inside one, a symbolic link to a file is read, but a link to a
+   * directory is not followed (as in Tweego).
+   */
+  sources: readonly SourceInput[];
+  /**
+   * Glob patterns for files to leave out of `sources`, matched against each file's
+   * path relative to the working directory (as `stats.files` lists it). Not the modules or head file.
+   * An {@link ExcludeGlob} matches against the path below its own folder instead (a config file's globs
+   * come that way when its folder's name holds glob characters).
+   */
+  exclude?: readonly (string | ExcludeGlob)[] | undefined;
+  /** Output mode. Default: 'html'. */
+  outputMode?: OutputMode | undefined;
+  /** Story format ID (e.g. 'sugarcube-2'). Default: StoryData's format, else 'sugarcube-2'. */
+  formatId?: string | undefined;
+  /** Name of the starting passage. Default: StoryData's `start`, else 'Start'. */
+  startPassage?: string | undefined;
+  /** Extra directories to search for story formats. */
+  formatPaths?: readonly string[] | undefined;
+  /** Also search TWEEGO_PATH env for formats. Default: true. */
+  useTweegoPath?: boolean | undefined;
+  /** Module files (JS, CSS or fonts) to inject into the head of HTML output. */
+  modules?: readonly string[] | undefined;
+  /** Raw HTML file to append to the head of HTML output. */
+  headFile?: string | undefined;
+  /** Trim white space at both ends of passage text, in Twee and HTML sources. Default: true. */
+  trim?: boolean | undefined;
+  /** Twee2 compatibility mode (`.tw2` and `.twee2` files always use it). Default: false. */
+  twee2Compat?: boolean | undefined;
+  /** Add the `debug` option to the story's options. Default: false. */
+  testMode?: boolean | undefined;
+  /** URLs of SFA-compatible index.json files, consulted after `formatUrls`. */
+  formatIndices?: readonly string[] | undefined;
+  /** URLs of format.js files, consulted after the local formats and before `formatIndices`. */
+  formatUrls?: readonly string[] | undefined;
+  /** Download no story formats (cached downloads are still used). Default: false. */
+  noRemote?: boolean | undefined;
+  /**
+   * Cancels the compile. Story format requests still in progress are aborted, and the compile
+   * rejects with the signal's reason. `watch()` aborts its builds, and stops watching, when it aborts.
+   */
+  signal?: AbortSignal | undefined;
+  /**
+   * Milliseconds each story format request (an index or a format.js) may take before it fails
+   * with a warning and the next source is tried. 0 turns the limit off. Default: 30000.
+   */
+  formatFetchTimeout?: number | undefined;
+  /**
+   * Milliseconds the search for the story format may take in all, over every request it makes.
+   * When the limit passes, the request in progress is stopped and the format URLs and indices not
+   * yet asked are read from the download cache only. 0 turns the limit off. Default: 120000.
+   */
+  formatResolutionTimeout?: number | undefined;
+  /**
+   * Whether the Story Formats Archive indices are asked after `formatIndices`. Set it to false so a
+   * project with its own archive never contacts the Story Formats Archive. Default: true.
+   */
+  useDefaultFormatIndices?: boolean | undefined;
+  /** Map alias tags to target tags (e.g. { library: 'script' }); each passage with an alias gets the target too. */
+  tagAliases?: Readonly<Record<string, string>> | undefined;
+  /** Emit source file and line as data- attributes on passage elements. Default: false. */
+  sourceInfo?: boolean | undefined;
+  /** Word counting method. Default: 'tweego'. */
+  wordCountMethod?: WordCountMethod | undefined;
+}
+interface CompileToFileOptions extends CompileOptions {
+  /**
+   * Output file path. It is never read as a source, even inside a source folder or
+   * reached through a symbolic link. Naming it as a source, a module or the head
+   * file (in any output mode, by any spelling, or as a hard link) is a TweeTsError
+   * (`OUTPUT_IS_INPUT`), and nothing is written. So is an existing file of a source
+   * type inside a source folder that is not an earlier twee-ts build. How it is
+   * written depends on what is there: see docs/cli.md, "Output safety".
+   */
+  outFile: string;
+}
+interface WatchOptions extends CompileToFileOptions {
+  /**
+   * Called after each build is written, including one whose diagnostics report errors. Builds
+   * run one at a time and are reported in order, each as it finishes, also while changes keep
+   * arriving: the changes made during a build go into one follow-up build after it.
+   */
+  onBuild?: ((result: CompileResult) => void) | undefined;
+  /**
+   * Called when a build fails with a fatal error (nothing is written), when `onBuild` throws,
+   * and when a watched path can't be watched (the other paths are still watched). An exception
+   * thrown here is reported to the console, and watching goes on. A TweeTsError no edit to the
+   * sources can fix (`OUTPUT_IS_INPUT`, `INVALID_OPTIONS`) also stops watching.
+   */
+  onError?: ((error: Error) => void) | undefined;
+}
+/**
+ * A warning or an error a build reports. `file` and `line` say where, when known. (`fatal` is not set
+ * by twee-ts: a build that cannot go on throws a TweeTsError instead.)
+ */
+type Diagnostic = {
+  readonly level: 'warning';
+  readonly message: string;
+  readonly file?: string;
+  readonly line?: number;
+} | {
+  readonly level: 'error';
+  readonly message: string;
+  readonly file?: string;
+  readonly line?: number;
+  readonly fatal?: boolean;
+};
+interface CompileResult {
+  /** The compiled output string (HTML, Twee, JSON, etc.). */
+  readonly output: string;
+  /** The story model, read-only. */
+  readonly story: ReadonlyStory;
+  /** The format used for compilation (undefined for non-HTML modes). */
+  readonly format?: StoryFormatInfo | undefined;
+  /** Warnings and errors. The output is built even when some are errors; check them. */
+  readonly diagnostics: readonly Diagnostic[];
+  /** Compilation statistics. */
+  readonly stats: CompileStats;
+}
+interface CompileStats {
+  /** Every passage. */
+  readonly passages: number;
+  /** The passages that are not info passages (special names, script, stylesheet, `Twine.*` tags…). */
+  readonly storyPassages: number;
+  /** The word count of the story passages (see `wordCountMethod`). */
+  readonly words: number;
+  /** The source files loaded, in order, as paths relative to the working directory when inside it. */
+  readonly files: readonly string[];
+  /** The module files and the head file the build injected (HTML output only), as Tweego's "External files". */
+  readonly externalFiles?: readonly string[];
+}
+/**
+ * Why a TweeTsError stopped a build:
+ * - `OUTPUT_IS_INPUT`: the output would overwrite an input (a source, module, head file, config file or story
+ *   format), or a source file of the output's type found in a source folder.
+ * - `INPUT_UNAVAILABLE`: an input the input policy makes fatal (the head file, the config file) can't be used.
+ * - `INVALID_OPTIONS`: an option is out of range or not usable (a format URL that is not http(s), say), or the
+ *   Vite plugin runs under a Vite older than 8.
+ * - `FORMAT_UNAVAILABLE`: `resolveRemoteFormat()` found the format nowhere and some source failed; the
+ *   error's diagnostics hold every failure.
+ * - `BUILD_FAILED`: anything else (no story format for HTML output, say).
+ */
+type TweeTsErrorCode = 'OUTPUT_IS_INPUT' | 'INPUT_UNAVAILABLE' | 'INVALID_OPTIONS' | 'FORMAT_UNAVAILABLE' | 'BUILD_FAILED';
+interface SourceLocation {
+  readonly file: string;
+  readonly line: number;
+}
+interface PassageMetadata {
+  position?: string;
+  size?: string;
+  [key: string]: string | undefined;
+}
+interface Passage {
+  name: string;
+  tags: string[];
+  text: string;
+  metadata?: PassageMetadata | undefined;
+  source?: SourceLocation | undefined;
+}
+type IFID = string & {
+  readonly __brand: 'IFID';
+};
+interface Twine1Metadata {
+  settings: Map<string, string>;
+}
+interface Twine2Metadata {
+  format: string;
+  formatVersion: string;
+  options: Map<string, boolean>;
+  start: string;
+  tags: string;
+  tagColors: Map<string, string>;
+  zoom: number;
+}
+interface Story {
+  name: string;
+  ifid: IFID;
+  passages: Passage[];
+  legacyIFID: IFID;
+  twine1: Twine1Metadata;
+  twine2: Twine2Metadata;
+}
+type ReadonlyPassage = Readonly<Omit<Passage, 'tags' | 'metadata'>> & {
+  readonly tags: readonly string[];
+  readonly metadata?: Readonly<PassageMetadata> | undefined;
+};
+type ReadonlyStory = Readonly<Omit<Story, 'passages' | 'twine1' | 'twine2'>> & {
+  readonly passages: readonly ReadonlyPassage[];
+  readonly twine1: {
+    readonly settings: ReadonlyMap<string, string>;
+  };
+  readonly twine2: Readonly<Omit<Twine2Metadata, 'options' | 'tagColors'>> & {
+    readonly options: ReadonlyMap<string, boolean>;
+    readonly tagColors: ReadonlyMap<string, string>;
+  };
+};
+type OmittingTag = 'Twine.private' | 'script' | 'stylesheet';
+type PassageOmission = {
+  readonly kind: 'special-name';
+  readonly name: 'StoryData' | 'StoryTitle';
+} | {
+  readonly kind: 'tag';
+  readonly tag: OmittingTag;
+} | {
+  readonly kind: 'empty-story-settings';
+};
+/** The output whose rules decide which passages a story emits as passages. */
+type PassageOutputTarget = 'twine1' | 'twine2';
+interface DecompileOptions {
+  /**
+   * Trim whitespace at both ends of passage text (and of the Twine 2 story stylesheet and script),
+   * as the Twee lexer does. When false, the stored text is kept exactly. Default: true.
+   */
+  readonly trim?: boolean | undefined;
+}
+interface InspectOptions {
+  /**
+   * Check link destinations against this output's passage rules. A link to a passage that the
+   * output leaves out (in Twine 2: `script`, `stylesheet` and `Twine.private` passages,
+   * StoryData, StoryTitle and an empty StorySettings; in Twine 1: `Twine.private` passages) is
+   * then a broken link, and says why. The passages it leaves out also give no links, as their
+   * text never reaches the player, except script passages, which Twine 2 output runs. Without a
+   * target, every source passage gives links, and a link is broken only when no passage has its
+   * name.
+   */
+  readonly target?: PassageOutputTarget | undefined;
+}
+interface StoryFormatInfo {
+  id: string;
+  /**
+   * The format's file (format.js or header.html): in a local format folder, in the download cache,
+   * or, for a download the cache could not store, the URL it was downloaded from.
+   */
+  filename: string;
+  isTwine2: boolean;
+  name: string;
+  version: string;
+  proofing: boolean;
+  author?: string;
+  description?: string;
+  image?: string;
+  url?: string;
+  license?: string;
+}
+interface Twine2FormatJSON {
+  name: string;
+  version: string;
+  proofing?: boolean;
+  source: string;
+  author?: string;
+  description?: string;
+  image?: string;
+  url?: string;
+  license?: string;
+}
+/**
+ * A parsed SemVer version. Build metadata is dropped, since it takes no part in precedence.
+ * Each prerelease identifier is kept as written ('beta', '1').
+ */
+interface SemVer {
+  readonly major: number;
+  readonly minor: number;
+  readonly patch: number;
+  readonly prerelease: readonly string[];
+}
+declare const ItemType: {
+  readonly Error: 0;
+  readonly EOF: 1;
+  readonly Header: 2;
+  readonly Name: 3;
+  readonly Tags: 4;
+  readonly Metadata: 5;
+  readonly Content: 6;
+};
+type ItemType = (typeof ItemType)[keyof typeof ItemType];
+interface LexerItem {
+  type: ItemType;
+  line: number;
+  pos: number;
+  val: string;
+}
+interface SFAIndexEntry {
+  name: string;
+  version: string;
+  proofing: boolean;
+  files: string[];
+  checksums: Record<string, string>;
+}
+interface SFAIndex {
+  twine1: SFAIndexEntry[];
+  twine2: SFAIndexEntry[];
+}
+/** Options for the network requests that fetch story formats and their indices. */
+interface RemoteFetchOptions {
+  /** Aborts the requests; the call then rejects with the signal's reason. */
+  readonly signal?: AbortSignal | undefined;
+  /** Milliseconds each request may take before it fails. 0 turns the limit off. Default: 30000. */
+  readonly timeout?: number | undefined;
+}
+/** Options of a lookup that may ask several sources, as `resolveRemoteFormat()` does. */
+interface RemoteResolveOptions extends RemoteFetchOptions {
+  /** SFA-compatible index.json URLs, asked in order after `urls`. */
+  readonly indices?: readonly string[] | undefined;
+  /** Direct format.js URLs, asked first, in order. */
+  readonly urls?: readonly string[] | undefined;
+  /**
+   * Milliseconds the whole lookup may take, over every request. When it passes, the request in
+   * progress is stopped and the sources not yet asked are read from the download cache only. 0 turns
+   * the limit off. Default: 120000.
+   */
+  readonly resolutionTimeout?: number | undefined;
+  /** Whether the Story Formats Archive indices are asked after the given indices. Default: true. */
+  readonly useDefaultIndices?: boolean | undefined;
+}
+interface FileCacheEntry {
+  readonly mtimeMs: number;
+  /**
+   * Identity of the parse options (`trim`, `twee2Compat`) the entry was parsed with. An entry is
+   * reused only when this matches the current options; an entry without it is treated as stale
+   * and reparsed. The value is opaque: leave it to twee-ts to set.
+   */
+  readonly parseOptionsKey?: string;
+  /**
+   * What else identifies the file's contents besides `mtimeMs` (its size, inode and status-change
+   * time), so a write that keeps the modification time is still seen. An entry is reused only when
+   * this matches too; an entry without it is treated as stale. The value is opaque: leave it to
+   * twee-ts to set.
+   */
+  readonly signature?: string;
+  /**
+   * The file's passages, frozen with everything they hold, so that no build and no caller can change what a
+   * later build replays. `CompileResult.story` holds copies of them, never these objects.
+   */
+  readonly passages: readonly Passage[];
+  /** The diagnostics of reading the file, frozen; each build reports copies of them. */
+  readonly diagnostics: readonly Diagnostic[];
+}
+/** The compile options a config file may set, with the same meaning (see CompileOptions). */
+type ConfigCompileOption = 'exclude' | 'outputMode' | 'formatId' | 'startPassage' | 'formatPaths' | 'formatIndices' | 'formatUrls' | 'useTweegoPath' | 'modules' | 'headFile' | 'trim' | 'twee2Compat' | 'testMode' | 'noRemote' | 'formatFetchTimeout' | 'formatResolutionTimeout' | 'useDefaultFormatIndices' | 'tagAliases' | 'sourceInfo' | 'wordCountMethod';
+/**
+ * A config file (`twee-ts.config.json`): the compile options it may set, which mean what they mean in
+ * `CompileOptions`, plus `sources` (paths only) and `output`.
+ */
+interface TweeTsConfig extends Pick<CompileOptions, ConfigCompileOption> {
+  /** Files or directories to compile. */
+  sources?: readonly string[] | undefined;
+  /** Output file path; "-" for standard output. */
+  output?: string | undefined;
+}
+//#endregion
+export { StoryFormatInfo as A, RemoteResolveOptions as C, SourceInput as D, SemVer as E, Twine2Metadata as F, WatchOptions as I, WordCountMethod as L, TweeTsErrorCode as M, Twine1Metadata as N, SourceLocation as O, Twine2FormatJSON as P, RemoteFetchOptions as S, SFAIndexEntry as T, PassageMetadata as _, DecompileOptions as a, ReadonlyPassage as b, FileCacheEntry as c, InspectOptions as d, ItemType as f, Passage as g, OutputMode as h, CompileToFileOptions as i, TweeTsConfig as j, Story as k, IFID as l, OmittingTag as m, CompileResult as n, Diagnostic as o, LexerItem as p, CompileStats as r, ExcludeGlob as s, CompileOptions as t, InlineSource as u, PassageOmission as v, SFAIndex as w, ReadonlyStory as x, PassageOutputTarget as y };