npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2024 – Pkg Stats / Ryan Hefner

dredd-transactions

v10.1.0

Published

Compiles HTTP Transactions (Request-Response pairs) from an API description document

Downloads

31,713

Readme

Dredd Transactions

npm version

Dredd Transactions library compiles HTTP Transactions (simple Request-Response pairs) from API description document.

Note: To better understand emphasized terms in this documentation, please refer to the Glossary of Terms. All data structures are described using the MSON format.

This project supersedes Blueprint Transactions library.

Features

  • Inherits parameters from parent Resource and Action sections.
  • Expands URI Templates.
  • Warns on undefined placeholders in URI Templates (both query and path).
  • Validates URI parameter types.
  • Selects first Request and first Response if multiple are specified in the API description document.

Deprecated Features

Note: These features are to be superseded by whatever comes out of the proposal in apiaryio/dredd#227.

Installation

npm install dredd-transactions

Development

Dredd Transactions library is written in JavaScript (ES2015+).

Usage

parse

Parses given API description document into API Elements with options specific to Dredd. Assumes that documents with unrecognizable format are API Blueprint. Turns any parser failures, including the unexpected ones, into API Elements annotations.

const parse = require('dredd-transactions/parse');
// const { parse } = require('dredd-transactions');

parse('# My API\n...', (error, parseResult) => {
  // ...
});

compile

Compiles HTTP Transactions from given API Elements. HTTP Transactions are a backbone data structure to Dredd.

const compile = require('dredd-transactions/compile');
// const { compile } = require('dredd-transactions');

const compileResult = compile(mediaType, apiElements, filename);

Note: The filename argument is optional and about to get deprecated, see #6

Data Structures

Parse Result (object)

Result of parsing.

  • mediaType: text/vnd.apiblueprint (string, default, nullable) - Media type of the input format, can be empty in case of some fatal errors
  • apiElements (API Elements) - API Elements parse result

Compile Result (object)

Result of compilation. Alongside compiled Transaction objects contains also errors and warnings, mainly from API description parser.

  • mediaType: text/vnd.apiblueprint (string, default, nullable) - Media type of the input format, defaults to API Blueprint format. Can be empty in case of some fatal errors.
  • transactions (array[Transaction]) - Compiled HTTP Transactions.
  • annotations (array[Annotation]) - Errors and warnings which occurred during parsing of the API description or during compilation of transactions.

Transaction (object)

Represents a single HTTP Transaction (Request-Response pair) and its location in the API description document. The location is provided in two forms, both deprecated as of now:

  • name - String representation, both human- and machine-readable.
  • origin - Object of references to nodes of API Elements derived from the original API description document.

Note: These two forms of locating HTTP Transactions are to be superseded by whatever comes out of the proposal in apiaryio/dredd#227.

Properties

  • request (object) - HTTP Request as described in API description document.
    • method
    • uri: /message (string) - Informative URI of the Request.
    • headers (array) - List of HTTP headers in their original order, with the original casing of the header name, including multiple headers of the same name.
      • (object)
        • name: Content-Type (string)
        • value: text/plain (string)
    • body: Hello world!\n (string)
  • response (object) - Expected HTTP Response as described in API description document.
    • status: 200 (string)
    • headers (array) - List of HTTP headers in their original order, with the original casing of the header name, including multiple headers of the same name.
      • (object)
        • name: Content-Type (string)
        • value: text/plain (string)
    • body (string, optional)
    • schema (string, optional)

Deprecated Properties

  • name: Hello world! > Retrieve Message (string) - Transaction Name, non-deterministic breadcrumb location of the HTTP Transaction within the API description document.
  • origin (object) - Object of references to nodes of API Elements derived from the original API description document.
    • filename: ./api-description.apib (string)
    • apiName: My Api (string)
    • resourceGroupName: Greetings (string)
    • resourceName: Hello, world! (string)
    • actionName: Retrieve Message (string)
    • exampleName: First example (string)

Note: These properties are to be superseded by whatever comes out of the proposal in apiaryio/dredd#227.

Annotation (object)

Description of an error or warning which occurred during parsing of the API description or during compilation of transactions.

Properties

  • type (enum[string])
    • error
    • warning
  • component (enum[string]) - In which component of the compilation process the annotation occurred
    • apiDescriptionParser
    • parametersValidation
    • uriTemplateExpansion
  • message (string) - Textual annotation. This is – in most cases – a human-readable message to be displayed to user
  • location (array, fixed, nullable) - Location of the annotation in the source file, represented by a single range of line and column number pairs if available, or by null otherwise
    • (array) - Start location
      • (number) - Line number
      • (number) - Column number
    • (array) - End location
      • (number) - Line number
      • (number) - Column number

Deprecated Properties

  • name: Hello world! > Retrieve Message (string) - Transaction Name, non-deterministic breadcrumb location of the relevant HTTP Transaction within the API description document.
  • origin (object) - Object of references to nodes of API Elements derived from the original API description document.
    • filename: ./api-description.apib (string)
    • apiName: My Api (string)
    • resourceGroupName: Greetings (string)
    • resourceName: Hello, world! (string)
    • actionName: Retrieve Message (string)
    • exampleName: First example (string)

Note: These properties are to be superseded by whatever comes out of the proposal in apiaryio/dredd#227.