feat: Simplify options.

BREAKING CHANGE: Some types related to options are removed/renamed.

The options code was some of the first I wrote for this project and it
was awkward to use. A lot of APIs expected a concrete options reader
instead of just the options interface in a read-only state.

The options reader is no longer exported, the new normalizeOptions
function should be used to get a read-only options object populated
with default values where necessary.

Where user-supplied options are accepted, the SparseOptions type is
accepted and then normalized.

Author: chriseppstein

packages/css-blocks/src/Block/AttrValue.ts

@@ -7,7 +7,7 @@ import {
 import { assertNever, assertNeverCalled } from "@opticss/util";
 
 import { ATTR_PRESENT } from "../BlockSyntax";
-import { OptionsReader } from "../OptionsReader";
+import { ReadonlyOptions } from "../options";
 import { OutputMode } from "../OutputMode";
 
 import { Attribute } from "./Attribute";
@@ -78,7 +78,7 @@ export class AttrValue extends Style<AttrValue, Block, Attribute, never> {
     return this.parent.asSource(this.value);
   }
 
-  public cssClass(opts: OptionsReader): string {
+  public cssClass(opts: ReadonlyOptions): string {
     switch (opts.outputMode) {
       case OutputMode.BEM:
         return `${this.parent.cssClass(opts)}${ this.isPresenceRule ? "" : `-${this.value}`}`;

packages/css-blocks/src/Block/Attribute.ts

@@ -9,7 +9,7 @@ import {
 import { assertNever, ObjectDictionary } from "@opticss/util";
 
 import { ATTR_PRESENT, IAttrToken as AttrToken } from "../BlockSyntax";
-import { OptionsReader } from "../OptionsReader";
+import { ReadonlyOptions } from "../options";
 import { OutputMode } from "../OutputMode";
 
 import { AttrValue } from "./AttrValue";
@@ -177,7 +177,7 @@ export class Attribute extends Inheritable<Attribute, Block, BlockClass, AttrVal
    * @param opts Option hash configuring output mode.
    * @returns String representing output class.
    */
-  cssClass(opts: OptionsReader) {
+  cssClass(opts: ReadonlyOptions) {
     switch (opts.outputMode) {
       case OutputMode.BEM:
         let cssClassName = this.blockClass.cssClass(opts);

packages/css-blocks/src/Block/Block.ts

@@ -16,7 +16,7 @@ import {
 } from "../BlockParser";
 import { isRootNode, toAttrToken } from "../BlockParser";
 import { BlockPath, CLASS_NAME_IDENT, ROOT_CLASS } from "../BlockSyntax";
-import { OptionsReader } from "../OptionsReader";
+import { ReadonlyOptions } from "../options";
 import { SourceLocation } from "../SourceLocation";
 import { CssBlockError, InvalidBlockSyntax } from "../errors";
 import { FileIdentifier } from "../importing";
@@ -367,7 +367,7 @@ export class Block
     return null;
   }
 
-  rewriteSelectorNodes(nodes: selectorParser.Node[], opts: OptionsReader): selectorParser.Node[] {
+  rewriteSelectorNodes(nodes: selectorParser.Node[], opts: ReadonlyOptions): selectorParser.Node[] {
     let newNodes: selectorParser.Node[] = [];
     for (let i = 0; i < nodes.length; i++) {
       let node = nodes[i];
@@ -382,7 +382,7 @@ export class Block
     return newNodes;
   }
 
-  rewriteSelectorToString(selector: ParsedSelector, opts: OptionsReader): string {
+  rewriteSelectorToString(selector: ParsedSelector, opts: ReadonlyOptions): string {
     let firstNewSelector = new CompoundSelector();
     let newSelector = firstNewSelector;
     let newCurrentSelector = newSelector;
@@ -402,14 +402,14 @@ export class Block
     return firstNewSelector.toString();
   }
 
-  rewriteSelector(selector: ParsedSelector, opts: OptionsReader): ParsedSelector {
+  rewriteSelector(selector: ParsedSelector, opts: ReadonlyOptions): ParsedSelector {
     // generating a string and re-parsing ensures the internal structure is consistent
     // otherwise the parent/next/prev relationships will be wonky with the new nodes.
     let s = this.rewriteSelectorToString(selector, opts);
     return parseSelector(s)[0];
   }
 
-  debug(opts: OptionsReader): string[] {
+  debug(opts: ReadonlyOptions): string[] {
     let result: string[] = [`Source: ${this.identifier}`, this.rootClass.asDebug(opts)];
     let sourceNames = new Set<string>(this.all().map(s => s.asSource()));
     let sortedNames = [...sourceNames].sort();

packages/css-blocks/src/Block/BlockClass.ts

@@ -3,7 +3,7 @@ import { isString } from "util";
 
 import { ATTR_PRESENT, IAttrToken as AttrToken, ROOT_CLASS } from "../BlockSyntax";
 import { BlockPath } from "../BlockSyntax";
-import { OptionsReader } from "../OptionsReader";
+import { ReadonlyOptions } from "../options";
 import { OutputMode } from "../OutputMode";
 
 import { AttrValue } from "./AttrValue";
@@ -184,7 +184,7 @@ export class BlockClass extends Style<BlockClass, Block, Block, Attribute> {
    * @param opts Option hash configuring output mode.
    * @returns String representing output class.
    */
-  public cssClass(opts: OptionsReader): string {
+  public cssClass(opts: ReadonlyOptions): string {
     switch (opts.outputMode) {
       case OutputMode.BEM:
         if (this.isRoot) {
@@ -219,7 +219,7 @@ export class BlockClass extends Style<BlockClass, Block, Block, Attribute> {
    * @param options  Options to pass to BlockClass' asDebug method.
    * @return Array of debug strings for this BlockClass
    */
-  debug(opts: OptionsReader): string[] {
+  debug(opts: ReadonlyOptions): string[] {
     let result: string[] = [];
     for (let style of this.all()) {
       result.push(style.asDebug(opts));

packages/css-blocks/src/Block/Style.ts

@@ -1,6 +1,6 @@
 import { Attr } from "@opticss/element-analysis";
 
-import { OptionsReader } from "../OptionsReader";
+import { ReadonlyOptions } from "../options";
 import { unionInto } from "../util/unionInto";
 
 import { AnyNode, Inheritable } from "./Inheritable";
@@ -41,7 +41,7 @@ export abstract class Style<
    * @param opts Option hash configuring output mode.
    * @returns The CSS class.
    */
-  public abstract cssClass(opts: OptionsReader): string;
+  public abstract cssClass(opts: ReadonlyOptions): string;
 
   /**
    * Return the source selector this `Style` was read from.
@@ -59,7 +59,7 @@ export abstract class Style<
    * including inherited classes.
    * @returns this object's css class and all inherited classes.
    */
-  cssClasses(opts: OptionsReader): string[] {
+  cssClasses(opts: ReadonlyOptions): string[] {
     let classes: string[] = [];
     for (let style of this.resolveStyles()) {
       classes.push(style.cssClass(opts));
@@ -110,7 +110,7 @@ export abstract class Style<
    * @param opts  Options for rendering cssClass.
    * @returns A debug string.
    */
-  asDebug(opts: OptionsReader) {
+  asDebug(opts: ReadonlyOptions) {
     return `${this.asSource()} => ${this.cssClasses(opts).map(n => `.${n}`).join(" ")}`;
   }
 

packages/css-blocks/src/BlockCompiler/ConflictResolver.ts

@@ -6,7 +6,7 @@ import selectorParser = require("postcss-selector-parser");
 import { Block, Style } from "../Block";
 import { getBlockNode } from "../BlockParser";
 import { RESOLVE_RE } from "../BlockSyntax";
-import { OptionsReader } from "../OptionsReader";
+import { ReadonlyOptions } from "../options";
 import { SourceLocation, sourceLocation } from "../SourceLocation";
 import * as errors from "../errors";
 import { QueryKeySelector } from "../query";
@@ -61,9 +61,9 @@ function updateConflict(t1: ConflictType, t2: ConflictType): ConflictType {
  * resolves property values accordingly.
  */
 export class ConflictResolver {
-  readonly opts: OptionsReader;
+  readonly opts: ReadonlyOptions;
 
-  constructor(opts: OptionsReader) {
+  constructor(opts: ReadonlyOptions) {
     this.opts = opts;
   }
 

packages/css-blocks/src/BlockCompiler/index.ts

@@ -8,21 +8,21 @@ import {
   parseBlockDebug,
   ROOT_CLASS,
 } from "../BlockSyntax";
-import { OptionsReader } from "../OptionsReader";
+import { normalizeOptions } from "../normalizeOptions";
 import { StyleAnalysis } from "../TemplateAnalysis/StyleAnalysis";
-import { PluginOptions } from "../options";
+import { SparseOptions, ReadonlyOptions } from "../options";
 
 import { ConflictResolver } from "./ConflictResolver";
 /**
  * Compiler that, given a Block will return a transformed AST
  * interface is `BlockParser.parse`.
  */
 export class BlockCompiler {
-  private opts: OptionsReader;
+  private opts: ReadonlyOptions;
   private postcss: typeof postcss;
 
-  constructor(postcssImpl: typeof postcss, opts?: PluginOptions) {
-    this.opts = new OptionsReader(opts);
+  constructor(postcssImpl: typeof postcss, opts?: SparseOptions) {
+    this.opts = normalizeOptions(opts);
     this.postcss = postcssImpl;
   }
 

packages/css-blocks/src/BlockParser/BlockFactory.ts

@@ -6,7 +6,8 @@ import { RawSourceMap } from "source-map";
 
 import { Block } from "../Block";
 import { FileIdentifier, ImportedFile, Importer } from "../importing";
-import { CssBlockOptionsReadonly } from "../options";
+import { ReadonlyOptions, SparseOptions } from "../options";
+import { normalizeOptions } from "../normalizeOptions";
 import { PromiseQueue } from "../util/PromiseQueue";
 
 import { BlockParser, ParsedSource } from "./BlockParser";
@@ -35,7 +36,7 @@ interface ErrorWithErrNum {
 export class BlockFactory {
   postcssImpl: typeof postcss;
   importer: Importer;
-  options: CssBlockOptionsReadonly;
+  options: ReadonlyOptions;
   blockNames: ObjectDictionary<number>;
   parser: BlockParser;
   preprocessors: Preprocessors;
@@ -45,9 +46,9 @@ export class BlockFactory {
   private paths: ObjectDictionary<string>;
   private preprocessQueue: PromiseQueue<PreprocessJob, ProcessedFile>;
 
-  constructor(options: CssBlockOptionsReadonly, postcssImpl = postcss) {
+  constructor(options: SparseOptions, postcssImpl = postcss) {
     this.postcssImpl = postcssImpl;
-    this.options = options;
+    this.options = normalizeOptions(options);
     this.importer = this.options.importer;
     this.preprocessors = this.options.preprocessors;
     this.parser = new BlockParser(options, this);
@@ -216,7 +217,7 @@ export class BlockFactory {
     if (firstPreprocessor) {
       if (syntax !== Syntax.css && this.preprocessors.css && !this.options.disablePreprocessChaining) {
         let cssProcessor = this.preprocessors.css;
-        preprocessor = (fullPath: string, content: string, options: CssBlockOptionsReadonly): Promise<ProcessedFile> => {
+        preprocessor = (fullPath: string, content: string, options: ReadonlyOptions): Promise<ProcessedFile> => {
           return firstPreprocessor!(fullPath, content, options).then(result => {
             let content = result.content.toString();
             return cssProcessor(fullPath, content, options, sourceMapFromProcessedFile(result)).then(result2 => {
@@ -234,7 +235,7 @@ export class BlockFactory {
     } else if (syntax !== Syntax.css) {
       throw new Error(`No preprocessor provided for ${syntaxName(syntax)}.`);
     } else {
-      preprocessor = (_fullPath: string, content: string, _options: CssBlockOptionsReadonly): Promise<ProcessedFile> => {
+      preprocessor = (_fullPath: string, content: string, _options: ReadonlyOptions): Promise<ProcessedFile> => {
         return Promise.resolve({
           content: content,
         });

packages/css-blocks/src/BlockParser/BlockParser.ts

@@ -1,10 +1,10 @@
 import * as postcss from "postcss";
 
 import { Block } from "../Block";
-import { OptionsReader } from "../OptionsReader";
+import { normalizeOptions } from "../normalizeOptions";
 import * as errors from "../errors";
 import { FileIdentifier } from "../importing";
-import { PluginOptions } from "../options";
+import { SparseOptions, ReadonlyOptions } from "../options";
 
 import { assertForeignGlobalAttribute } from "./features/assert-foreign-global-attribute";
 import { constructBlock } from "./features/construct-block";
@@ -32,11 +32,11 @@ export interface ParsedSource {
  * interface is `BlockParser.parse`.
  */
 export class BlockParser {
-  private opts: OptionsReader;
+  private opts: ReadonlyOptions;
   private factory: BlockFactory;
 
-  constructor(opts: PluginOptions, factory: BlockFactory) {
-    this.opts = new OptionsReader(opts);
+  constructor(opts: SparseOptions, factory: BlockFactory) {
+    this.opts = normalizeOptions(opts);
     this.factory = factory;
   }
 

packages/css-blocks/src/BlockParser/features/process-debug-statements.ts

@@ -3,15 +3,15 @@ import * as postcss from "postcss";
 
 import { Block } from "../../Block";
 import { BLOCK_DEBUG, parseBlockDebug } from "../../BlockSyntax";
-import { OptionsReader } from "../../OptionsReader";
+import { ReadonlyOptions } from "../../options";
 
 /**
  * Process all `@block-debug` statements, output debug statement to console or in comment as requested.
  * @param sourceFile File name of block in question.
  * @param root PostCSS Root for block.
  * @param block Block to resolve references for
  */
-export async function processDebugStatements(root: postcss.Root, block: Block, file: string, opts: OptionsReader) {
+export async function processDebugStatements(root: postcss.Root, block: Block, file: string, opts: ReadonlyOptions) {
   root.walkAtRules(BLOCK_DEBUG, (atRule) => {
     let { block: ref, channel } = parseBlockDebug(atRule, file, block);
     let debugStr = ref.debug(opts);

packages/css-blocks/src/BlockParser/preprocessing.ts

@@ -5,7 +5,7 @@ import {
 } from "source-map";
 
 import {
-  CssBlockOptionsReadonly,
+  ReadonlyOptions,
 } from "../options";
 
 export enum Syntax {
@@ -41,7 +41,7 @@ export interface ProcessedFile {
 }
 
 // export type ContentPreprocessor = (content: string) => Promise<ProcessedFile>;
-export type Preprocessor = (fullPath: string, content: string, options: CssBlockOptionsReadonly, sourceMap?: RawSourceMap | string) => Promise<ProcessedFile>;
+export type Preprocessor = (fullPath: string, content: string, options: ReadonlyOptions, sourceMap?: RawSourceMap | string) => Promise<ProcessedFile>;
 
 /**
  * A map of supported syntaxes to the preprocessor function for that syntax.

packages/css-blocks/src/OptionsReader.ts

@@ -2,24 +2,24 @@ import * as postcss from "postcss";
 
 import { BlockCompiler } from "./BlockCompiler";
 import { BlockFactory } from "./BlockParser";
-import { OptionsReader } from "./OptionsReader";
+import { normalizeOptions } from "./normalizeOptions";
 import * as errors from "./errors";
-import { PluginOptions } from "./options";
-export { PluginOptions } from "./options";
+import { SparseOptions, ReadonlyOptions } from "./options";
+export { SparseOptions } from "./options";
 
 /**
  * CSS Blocks PostCSS plugin.
  */
 export class Plugin {
-  private opts: OptionsReader;
+  private opts: ReadonlyOptions;
   private postcss: typeof postcss;
 
   /**
    * @param  postcssImpl  PostCSS instance to use
    * @param  opts  Optional plugin config options
    */
-  constructor(postcssImpl: typeof postcss, opts?: PluginOptions) {
-    this.opts = new OptionsReader(opts);
+  constructor(postcssImpl: typeof postcss, opts?: SparseOptions) {
+    this.opts = normalizeOptions(opts);
     this.postcss = postcssImpl;
   }