twoslash

  • Version 0.3.8
  • Published
  • 138 kB
  • 2 dependencies
  • MIT license

Install

npm i twoslash
yarn add twoslash
pnpm add twoslash

Overview

Markup for generating rich type information in your documentations ahead of time

Index

Variables

variable defaultCompilerOptions

const defaultCompilerOptions: CompilerOptions;

    variable defaultHandbookOptions

    const defaultHandbookOptions: HandbookOptions;

      Functions

      function convertLegacyOptions

      convertLegacyOptions: <T extends TwoslashOptionsLegacy>(
      opts: T
      ) => Omit<T, 'defaultOptions' | 'defaultCompilerOptions'>;

        function convertLegacyReturn

        convertLegacyReturn: (result: TwoslashReturn) => TwoslashReturnLegacy;
        • Covert the new return type to the old one

        function createTwoslasher

        createTwoslasher: (opts?: TwoslashOptions) => TwoslashInstance;
        • Create a Twoslash instance with cached TS environments

        function findCutNotations

        findCutNotations: (
        code: string,
        meta: Pick<TwoslashReturnMeta, 'removals'>
        ) => Range[];

          function findFlagNotations

          findFlagNotations: (
          code: string,
          customTags: string[],
          tsOptionDeclarations: CompilerOptionDeclaration[]
          ) => ParsedFlagNotation[];

            function findQueryMarkers

            findQueryMarkers: (
            code: string,
            meta: Pick<
            TwoslashReturnMeta,
            'positionQueries' | 'positionCompletions' | 'positionHighlights' | 'removals'
            >,
            pc: ReturnType<typeof createPositionConverter>
            ) => Pick<
            TwoslashReturnMeta,
            'removals' | 'positionQueries' | 'positionCompletions' | 'positionHighlights'
            >;

              function getObjectHash

              getObjectHash: (obj: any) => string;

                function removeTwoslashNotations

                removeTwoslashNotations: (code: string, customTags?: string[]) => string;
                • A fallback function to strip out twoslash annotations from a string and does nothing else.

                  This function does not returns the meta information about the removals. It's designed to be used as a fallback when Twoslash fails.

                function twoslasher

                twoslasher: (
                code: string,
                lang: string,
                opts?: TwoslashOptions
                ) => TwoslashReturn;
                • Get type results from a code sample

                function twoslasherLegacy

                twoslasherLegacy: (
                code: string,
                lang: string,
                opts?: TwoslashOptionsLegacy
                ) => TwoslashReturnLegacy;
                • Compatability wrapper to align with @typescript/twoslash's input/output

                  Deprecated

                  migrate to twoslasher instead

                function validateCodeForErrors

                validateCodeForErrors: (
                relevantErrors: NodeErrorWithoutPosition[],
                handbookOptions: { errors: number[] },
                vfsRoot: string
                ) => void;
                • To ensure that errors are matched up right

                Classes

                class TwoslashError

                class TwoslashError extends Error {}

                  constructor

                  constructor(
                  title: string,
                  description: string,
                  recommendation: string,
                  code?: string
                  );

                    property code

                    code: string;

                      property description

                      description: string;

                        property recommendation

                        recommendation: string;

                          property title

                          title: string;

                            Interfaces

                            interface CompilerOptionDeclaration

                            interface CompilerOptionDeclaration {}

                              property element

                              element?: CompilerOptionDeclaration;

                                property name

                                name: string;

                                  property type

                                  type: 'list' | 'boolean' | 'number' | 'string' | 'object' | Map<string, any>;

                                    interface CreateTwoslashOptions

                                    interface CreateTwoslashOptions extends TwoslashExecuteOptions {}

                                      property cache

                                      cache?: boolean | Map<string, VirtualTypeScriptEnvironment>;
                                      • Cache the ts envs based on compiler options, defaults to true

                                      property customTransformers

                                      customTransformers?: CustomTransformers;
                                      • Allows applying custom transformers to the emit result, only useful with the showEmit output

                                      property fsCache

                                      fsCache?: boolean;
                                      • Cache file system requests

                                        true

                                      property fsMap

                                      fsMap?: Map<string, string>;
                                      • An optional Map object which is passed into @typescript/vfs - if you are using twoslash on the web then you'll need this to set up your lib *.d.ts files. If missing, it will use your fs.

                                      property tsLibDirectory

                                      tsLibDirectory?: string;
                                      • Absolute path to the directory to look up built-in TypeScript .d.ts files.

                                      property tsModule

                                      tsModule?: TS;
                                      • An optional copy of the TypeScript import, if missing it will be require'd.

                                      property vfsRoot

                                      vfsRoot?: string;
                                      • The cwd for the folder which the virtual fs should be overlaid on top of when using local fs, opts to process.cwd() if not present

                                      interface HandbookOptions

                                      interface HandbookOptions {}
                                      • Available inline flags which are not compiler flags

                                      property errors

                                      errors: number[];
                                      • An array of TS error codes, which you write as space separated - this is so the tool can know about unexpected errors

                                      property keepNotations

                                      keepNotations: boolean;
                                      • Do not remove twoslash notations from output code, the nodes will have the position of the input code. false

                                      property noErrors

                                      noErrors: boolean | number[];
                                      • Suppress errors for diagnostics and display

                                        Setting true to suppress all errors, or an array of error codes to suppress

                                      property noErrorsCutted

                                      noErrorsCutted: boolean;
                                      • Do not check errors in the cutted code. false

                                      property noErrorValidation

                                      noErrorValidation: boolean;
                                      • Declare that you don't need to validate that errors have corresponding annotations, defaults to false

                                      property noStaticSemanticInfo

                                      noStaticSemanticInfo: boolean;
                                      • Whether to disable the pre-cache of LSP calls for interesting identifiers, defaults to false

                                      property showEmit

                                      showEmit: boolean;
                                      • Shows the JS equivalent of the TypeScript code instead

                                      property showEmittedFile

                                      showEmittedFile?: string;
                                      • Must be used with showEmit, lets you choose the file to present instead of the source - defaults to index.js which means when you just use showEmit above it shows the transpiled JS.

                                      interface ParsedFlagNotation

                                      interface ParsedFlagNotation {}

                                        property end

                                        end: number;

                                          property name

                                          name: string;

                                            property start

                                            start: number;

                                              property type

                                              type: 'compilerOptions' | 'handbookOptions' | 'tag' | 'unknown';

                                                property value

                                                value: any;

                                                  interface TwoslashExecuteOptions

                                                  interface TwoslashExecuteOptions
                                                  extends Partial<
                                                  Pick<
                                                  TwoslashReturnMeta,
                                                  'positionQueries' | 'positionCompletions' | 'positionHighlights'
                                                  >
                                                  > {}
                                                  • Options for twoslash instance

                                                  property compilerOptions

                                                  compilerOptions?: CompilerOptions;
                                                  • Allows setting any of the compiler options from outside the function

                                                  property customTags

                                                  customTags?: string[];
                                                  • A set of known // @[tags] tags to extract and not treat as a comment

                                                  property extraFiles

                                                  extraFiles?: ExtraFiles;
                                                  • Extra files to to added to the virtual file system, or prepended/appended to existing files

                                                  property filterNode

                                                  filterNode?: (node: NodeWithoutPosition) => boolean;
                                                  • A custom predicate to filter out nodes for further processing

                                                  property handbookOptions

                                                  handbookOptions?: Partial<HandbookOptions>;
                                                  • Allows setting any of the handbook options from outside the function, useful if you don't want LSP identifiers

                                                  property shouldGetHoverInfo

                                                  shouldGetHoverInfo?: (
                                                  identifier: string,
                                                  start: number,
                                                  filename: string
                                                  ) => boolean;
                                                  • A custom hook to filter out hover info for certain identifiers

                                                  interface TwoslashInstance

                                                  interface TwoslashInstance {}

                                                    property getCacheMap

                                                    getCacheMap: () => Map<string, VirtualTypeScriptEnvironment> | undefined;
                                                    • Get the internal cache map

                                                    call signature

                                                    (
                                                    code: string,
                                                    extension?: string,
                                                    options?: TwoslashExecuteOptions
                                                    ): TwoslashReturn;
                                                    • Run Twoslash on a string of code, with a particular extension

                                                    interface TwoslashOptions

                                                    interface TwoslashOptions extends CreateTwoslashOptions, TwoslashExecuteOptions {}
                                                    • Options for the twoslasher function

                                                    interface TwoslashOptionsLegacy

                                                    interface TwoslashOptionsLegacy extends TwoslashExecuteOptions {}

                                                      property defaultCompilerOptions

                                                      defaultCompilerOptions?: CompilerOptions;
                                                      • @deprecated, use compilerOptions instead

                                                      property defaultOptions

                                                      defaultOptions?: Partial<HandbookOptions>;
                                                      • @deprecated, use handbookOptions instead

                                                      interface TwoslashReturn

                                                      interface TwoslashReturn extends TwoslashGenericResult {}

                                                        property meta

                                                        meta: TwoslashReturnMeta;
                                                        • The meta information the twoslash run

                                                        index signature

                                                        get queries(): NodeQuery[];

                                                          index signature

                                                          get completions(): NodeCompletion[];

                                                            index signature

                                                            get errors(): NodeError[];

                                                              index signature

                                                              get highlights(): NodeHighlight[];

                                                                index signature

                                                                get hovers(): NodeHover[];

                                                                  index signature

                                                                  get tags(): NodeTag[];

                                                                    interface TwoslashReturnLegacy

                                                                    interface TwoslashReturnLegacy {}

                                                                      property code

                                                                      code: string;
                                                                      • The output code, could be TypeScript, but could also be a JS/JSON/d.ts

                                                                      property errors

                                                                      errors: {
                                                                      renderedMessage: string;
                                                                      id: string;
                                                                      category: 0 | 1 | 2 | 3;
                                                                      code: number;
                                                                      start: number | undefined;
                                                                      length: number | undefined;
                                                                      line: number | undefined;
                                                                      character: number | undefined;
                                                                      }[];
                                                                      • Diagnostic error messages which came up when creating the program

                                                                      property extension

                                                                      extension: string;
                                                                      • The new extension type for the code, potentially changed if they've requested emitted results

                                                                      property highlights

                                                                      highlights: {
                                                                      kind: 'highlight';
                                                                      /** The index of the text in the file */
                                                                      start: number;
                                                                      /** What line is the highlighted identifier on? */
                                                                      line: number;
                                                                      /** At what index in the line does the caret represent */
                                                                      offset: number;
                                                                      /** The text of the token which is highlighted */
                                                                      text?: string;
                                                                      /** The length of the token */
                                                                      length: number;
                                                                      }[];
                                                                      • Requests to highlight a particular part of the code

                                                                      property playgroundURL

                                                                      playgroundURL: string;
                                                                      • The URL for this sample in the playground

                                                                      property queries

                                                                      queries: {
                                                                      kind: 'query' | 'completions';
                                                                      /** What line is the highlighted identifier on? */
                                                                      line: number;
                                                                      /** At what index in the line does the caret represent */
                                                                      offset: number;
                                                                      /** The text of the node which is highlighted */
                                                                      text?: string;
                                                                      /** Any attached JSDocs */
                                                                      docs?: string | undefined;
                                                                      /** The node start which the query indicates */
                                                                      start: number;
                                                                      /** The length of the node */
                                                                      length: number;
                                                                      /** Results for completions at a particular point */
                                                                      completions?: typescript.CompletionEntry[];
                                                                      completionsPrefix?: string;
                                                                      }[];
                                                                      • Requests to use the LSP to get info for a particular symbol in the source

                                                                      property staticQuickInfos

                                                                      staticQuickInfos: {
                                                                      /** The string content of the node this represents (mainly for debugging) */
                                                                      targetString: string;
                                                                      /** The base LSP response (the type) */
                                                                      text: string;
                                                                      /** Attached JSDoc info */
                                                                      docs: string | undefined;
                                                                      /** The index of the text in the file */
                                                                      start: number;
                                                                      /** how long the identifier */
                                                                      length: number;
                                                                      /** line number where this is found */
                                                                      line: number;
                                                                      /** The character on the line */
                                                                      character: number;
                                                                      }[];
                                                                      • An array of LSP responses identifiers in the sample

                                                                      property tags

                                                                      tags: {
                                                                      /** What was the name of the tag */
                                                                      name: string;
                                                                      /** Where was it located in the original source file */
                                                                      line: number;
                                                                      /** What was the text after the `// @tag: ` string (optional because you could do // @tag on it's own line without the ':') */
                                                                      annotation?: string;
                                                                      }[];
                                                                      • The extracted twoslash commands for any custom tags passed in via customTags

                                                                      interface TwoslashReturnMeta

                                                                      interface TwoslashReturnMeta {}

                                                                        property compilerOptions

                                                                        compilerOptions: CompilerOptions;
                                                                        • Resolved compiler options

                                                                        property extension

                                                                        extension: string;
                                                                        • The new extension type for the code, potentially changed if they've requested emitted results

                                                                        property flagNotations

                                                                        flagNotations: ParsedFlagNotation[];
                                                                        • Flags which were parsed from the code

                                                                        property handbookOptions

                                                                        handbookOptions: HandbookOptions;
                                                                        • Resolved handbook options

                                                                        property positionCompletions

                                                                        positionCompletions: number[];
                                                                        • Positions of completions in the code

                                                                        property positionHighlights

                                                                        positionHighlights: [start: number, end: number, text?: string][];
                                                                        • Positions of errors in the code

                                                                        property positionQueries

                                                                        positionQueries: number[];
                                                                        • Positions of queries in the code

                                                                        property removals

                                                                        removals: Range[];
                                                                        • Ranges of text which should be removed from the output

                                                                        property virtualFiles

                                                                        virtualFiles: VirtualFile[];
                                                                        • The virtual files which were created

                                                                        interface VirtualFile

                                                                        interface VirtualFile {}

                                                                          property append

                                                                          append?: string;

                                                                            property content

                                                                            content: string;

                                                                              property extension

                                                                              extension: string;

                                                                                property filename

                                                                                filename: string;

                                                                                  property filepath

                                                                                  filepath: string;

                                                                                    property offset

                                                                                    offset: number;

                                                                                      property prepend

                                                                                      prepend?: string;

                                                                                        property supportLsp

                                                                                        supportLsp?: boolean;

                                                                                          Type Aliases

                                                                                          type ExtraFiles

                                                                                          type ExtraFiles = Record<
                                                                                          string,
                                                                                          | string
                                                                                          | {
                                                                                          prepend?: string;
                                                                                          append?: string;
                                                                                          }
                                                                                          >;

                                                                                            type TS

                                                                                            type TS = typeof typescript;

                                                                                              type TwoslashFunction

                                                                                              type TwoslashFunction = (
                                                                                              code: string,
                                                                                              extension?: string,
                                                                                              options?: TwoslashExecuteOptions
                                                                                              ) => TwoslashReturn;

                                                                                                Package Files (3)

                                                                                                Dependencies (2)

                                                                                                Dev Dependencies (1)

                                                                                                Peer Dependencies (1)

                                                                                                Badge

                                                                                                To add a badge like this onejsDocs.io badgeto your package's README, use the codes available below.

                                                                                                You may also use Shields.io to create a custom badge linking to https://www.jsdocs.io/package/twoslash.

                                                                                                • Markdown
                                                                                                  [![jsDocs.io](https://img.shields.io/badge/jsDocs.io-reference-blue)](https://www.jsdocs.io/package/twoslash)
                                                                                                • HTML
                                                                                                  <a href="https://www.jsdocs.io/package/twoslash"><img src="https://img.shields.io/badge/jsDocs.io-reference-blue" alt="jsDocs.io"></a>