draper

Surgeon

Declarative DOM extraction expression evaluator.

• Supports selector nesting.
• Integrates match validation.
• Works in Node.js or in browser.
• Uses domain-specific language (DSL) to:
  • select a defined number of nodes (Quantifier expression)
  • access attribute and property values
  • use user-defined functions to format, filter and validate data

Powerful, succinct, declarative API.

articles:
- select article
- body:
  - select .body
  - extract property innerHTML
  imageUrl:
  - select img
  - extract attribute src
  summary:
  - select .body p:first-child
  - extract property innerHTML
  - format text
  title:
  - select .title
  - extract property textContent
pageName:
- select .body
- extract property innerHTML

Have you got suggestions for improvement? I am all ears.

• Error handling
• Debugging

Error handling

Surgeon throws the following errors to indicate a predictable error state. Use instanceof operator to determine the error type.

Note:

Surgeon errors are non-recoverable, i.e. a selector cannot proceed if it encounters an error. This design ensures that your selectors are capturing the expected data.

If a selector breaks, adjust the select query to increase selector specificity, adjust filter and/or validation criteria.

Name	Description
NotFoundError	Thrown when an attempt is made to retrieve a non-existent attribute or property.
UnexpectedResultCountError	Thrown when a select action quantifier is not satisfied.
InvalidDataError	Thrown when a resulting data does not pass the validation.
SurgeonError	A generic error. All other Surgeon errors extend from SurgeonError.

Example:

import {
  InvalidDataError
} from 'surgeon';

const subject = `
  <div class="foo">bar</div>
`;

try {
  x([
    'select .foo',
    'test /baz/'
  ], subject);
} catch (error) {
  if (error instanceof InvalidDataError) {
    // Handle data validation error.
  } else {
    throw error;
  }
}

Debugging

Surgeon is using debug to log debugging information.

Export DEBUG=surgeon:* environment variable to enable Surgeon debug log.