Style to Object Parser

Common errors

• Error: Cannot parse input: 'top'

  cause The input string provided to `parse` is a malformed CSS declaration, specifically an incomplete property without a corresponding value and semicolon.
  fix Provide a complete and valid CSS style declaration, for example, change `'top'` to `'top: 0;'`, or implement `try...catch` error handling around calls to `parse`.

• TypeError: (0 , style_to_object_1.default) is not a function

  cause In a CommonJS environment, `require('style-to-object')` is being used directly to invoke the parser, but the default export is located under the `.default` property.
  fix Update the CommonJS import statement to `const parse = require('style-to-object').default;` to correctly access the default export.

• Property 'parse' does not exist on type 'typeof import("/path/to/node_modules/style-to-object/index")'.

  cause This TypeScript error occurs when attempting to use a named import for `parse` (e.g., `import { parse } from 'style-to-object';`) when `parse` is actually the default export.
  fix Correct the import statement to `import parse from 'style-to-object';` for the default export.

Warnings

• breaking For CommonJS users, the default export now requires accessing the `.default` property (e.g., `require('style-to-object').default`) since version 1.0.0. Direct `require('style-to-object')` will result in a `TypeError`.
  Fix: Update CommonJS imports to `const parse = require('style-to-object').default;`.
• gotcha Providing malformed CSS strings, such as incomplete declarations like `'top'` or unclosed comments like `'/*'`, will cause the `parse` function to throw a synchronous `Error`. It does not gracefully return `null` for these specific malformations.
  Fix: Ensure input strings are syntactically valid CSS declarations or wrap calls to `parse` in a `try...catch` block to handle potential errors.
• gotcha When `parse` is called with a second argument as an iterator function, it will always return `null`, regardless of the input string's validity or the processing done within the callback. The output must be collected directly by the iterator function.
  Fix: Collect any desired processed data from within the scope of the iterator function, as the `parse` function itself will not return a value when an iterator is provided.
• gotcha Early versions of the 1.x series (specifically <=1.0.4 and <=1.0.10) experienced issues with correctly exporting ESM types, which could lead to TypeScript compilation errors depending on the module resolution settings. These issues were subsequently addressed.
  Fix: Upgrade `style-to-object` to version `1.0.11` or higher to benefit from improved ESM type support and fixes.

Install

• npm install style-to-object npm
• yarn add style-to-object yarn
• pnpm add style-to-object pnpm

Imports

• parse
  wrong:

  import { parse } from 'style-to-object';

  correct:

  import parse from 'style-to-object';

  The primary parsing function is the default export for ES Modules.
• parse
  wrong:

  const parse = require('style-to-object');

  correct:

  const parse = require('style-to-object').default;

  For CommonJS, the default export is accessible via the `.default` property since v1.0.0.
• StyleObject
  wrong:

  import { StyleObject } from 'style-to-object';

  correct:

  import type { StyleObject } from 'style-to-object';

  This is a TypeScript type interface for the parsed style object. Use `import type` for type-only imports.

Quickstart

This quickstart demonstrates how to parse CSS inline style strings into JavaScript objects, including basic usage, custom processing with the iterator, and error handling for invalid or malformed input. It shows both the object return and the null return when an iterator is used.

import parse from 'style-to-object';
import type { StyleObject } from 'style-to-object';

/**
 * Parses a CSS style string into a JavaScript object.
 * Handles potential parsing errors and demonstrates iterator usage.
 */
function processStyleString(styleString: string): StyleObject | null {
  try {
    // Basic usage: parse a string to an object
    const parsedStyle = parse(styleString);
    console.log(`Parsed style for "${styleString}":`, parsedStyle);
    return parsedStyle;
  } catch (error: any) {
    console.error(`Error parsing style "${styleString}":`, error.message);
    return null;
  }
}

// Example 1: Basic conversion
processStyleString('color: #C0FFEE; background: #BADA55;');
// Expected output: { color: '#C0FFEE', background: '#BADA55' }

// Example 2: Using the iterator for custom processing
const customOutput: [string, string][] = [];
const iteratorResult = parse('font-size: 16px; margin: 10px;', (name, value) => {
  customOutput.push([name, value]);
});
console.log('Custom iterated output:', customOutput);
console.log('Result when using iterator (always null):', iteratorResult);
// Expected output: [['font-size', '16px'], ['margin', '10px']], null

// Example 3: Handling invalid input that returns null
processStyleString('top:');

// Example 4: Handling malformed input that throws an error
processStyleString('top');