Refactor the options structure?

[eemeli]

As an offshoot of the discussion in #190, I'm now thinking about refactoring and recategorising the options that control various stages. I would appreciate some feedback on this. The general idea here is to flatten scalar options into document options, and then to split them into related sets, and to get rid of user-modifiable cross-document default values. This is where I'm at so far:

// options for `new Document()`
interface DocumentOptions {
  anchorPrefix?: string;
  customTags?: (TagId | Tag)[] | ((tags: Tag[]) => Tag[]);
  merge?: boolean;
  schema?: "core" | "failsafe" | "json" | "yaml-1.1";
  version?: "1.0" | "1.1" | "1.2";
}

// options for `doc.parse()`
interface ParseOptions {
  intAsBigInt?: boolean;
  keepCstNodes?: boolean;
  keepNodeTypes?: boolean;
  prettyErrors?: boolean;
  resolveKnownTags?: boolean;
  sortMapEntries?: boolean | ((a: Pair, b: Pair) => number);
}

// options for `doc.toJS()`
interface ConstructOptions {
  mapAsMap?: boolean;
  maxAliasCount?: number;
}

// options for `doc.createNode()`
interface CreateNodeOptions {
  replacer?: any[] | ((key: any, value: any) => boolean);
  tag?: string;
  wrapScalars?: boolean;
}

// options for `doc.toString()`
interface StringifyOptions {
  binLineWidth?: number;
  binType?: Scalar.Type;
  boolStr?: { true: string, false: string };
  indent?: number;
  indentSeq?: boolean;
  lineWidth?: number;
  minContentWidth?: number;
  nullStr?: string;
  simpleKeys?: boolean;
}

// these belong in StringifyOptions, but need more work
namespace scalarOptions {
  interface Str {
    defaultType: Scalar.Type;
    defaultKeyType: Scalar.Type;
    defaultQuoteSingle: boolean;
    doubleQuoted: {
      jsonEncoding: boolean;
      minMultiLineLength: number;
    };
  }
}

Some functions would then combine more than one of these options:

• YAML.parseDocument(): DocumentOptions & ParseOptions
• YAML.parse(): DocumentOptions & ParseOptions & ConstructOptions
• YAML.stringify(): DocumentOptions & StringifyOptions

Doing this would allow for YAML.defaultOptions and YAML.scalarOptions to be dropped, and for the options structure to be flattened. Relatively little should change for any of the options that you're currently able to pass a document, but options controlling scalars would get a complete overhaul.

Regarding doc.toJS() and doc.toString(), I'm not sure yet whether an options bag passed in to the document constructor should provide the defaults for these, or if they should only use options directly passed in.