API Elements JavaScript Library

Common errors

• TypeError: Cannot read properties of undefined (reading 'copy')

  cause Attempting to access properties like `parseResult.api.copy` when `parseResult.api` is `null` or `undefined`, usually because the parsed API description lacks a main API category or a copy element within it.
  fix Always check for the existence of intermediate elements (e.g., `if (parseResult.api && parseResult.api.copy)`) before attempting to access their properties, especially when dealing with potentially incomplete or malformed API descriptions.

• Error: Not a Refract element: <value>

  cause This error typically occurs when a function expecting an API Element (part of the Refract AST) receives a plain JavaScript object or a primitive value instead.
  fix Ensure that any arguments passed to API Elements functions or methods are instances of `namespace.elements.SomeElement` or other valid Refract elements. Convert plain data structures into appropriate `minim` or `api-elements` element types before use.

• JSON.parse: unexpected end of data at line 1 column 1 of the JSON data

  cause When deserializing API Elements from a JSON string, this error indicates that the input JSON is malformed or empty, preventing the serializer from correctly processing it.
  fix Verify that the JSON string passed to `namespace.serialiser.deserialise` is valid, complete, and represents a proper API Elements structure. Use a JSON linter or validator to check the input.

Warnings

• gotcha The `api-elements` package itself has a relatively low version (0.3.x) which can imply a less stable API compared to 1.0+ packages. While its underlying parsers are more active, direct usage of `api-elements` might involve more frequent adjustments.
  Fix: Refer to the `api-elements.js` GitHub repository for the latest API documentation and examples. Consider pinning to exact patch versions if stability is critical.
• breaking When consuming `Host URI metadata` from `openapi2-parser`, the default scheme changed from potentially undefined to `https` if `schemes` is not explicitly defined in the OpenAPI 2.0 specification. This might affect applications relying on an `http` default or a partial URI.
  Fix: Ensure your OpenAPI 2.0 definitions explicitly define the `schemes` property (e.g., `schemes: ["http"]` or `schemes: ["https"]`) to control the generated host URI, or update your application logic to expect `https` by default for missing schemes.
• gotcha Handling references to JSON paths that prefix the current path (e.g., `$ref: '#/definitions/User'` from a path inside `UserList`) was buggy in `openapi2-parser` when generating example JSON bodies. This could lead to incorrect or incomplete examples.
  Fix: Upgrade to `@apielements/openapi2-parser@0.32.6` or newer to ensure correct generation of example JSON bodies from Swagger/OpenAPI 2.0 schemas with complex internal references.
• gotcha Support for OpenAPI 3.1 features in `@apielements/openapi3-parser` is progressive. While basic `const` and array `type` support for 'Schema Object' is present, not all OpenAPI 3.1 features and fields are fully supported and may emit warnings.
  Fix: Be aware of emitted 'unsupported warnings' when parsing OpenAPI 3.1 definitions. Test your specific 3.1 features with the parser and check its release notes for ongoing support and limitations. Provide feedback to the maintainers for missing features.
• deprecated Older versions of `api-elements` might have unexpected behavior when generating values from elements, especially for objects with only undefined property values, or when handling headers without explicit values. These have been addressed in recent patches.
  Fix: Update the `api-elements` package to at least `0.3.1` to benefit from fixes in value generation logic, and ensure `apib-serializer` is at `0.16.3` or newer for correct header handling.

Install

• npm install api-elements npm
• yarn add api-elements yarn
• pnpm add api-elements pnpm

Imports

• Namespace
  wrong:

  const { Namespace } = require('api-elements');

  correct:

  import { Namespace } from 'api-elements';

  While the README shows `const apiElements = require('api-elements'); const namespace = new apiElements.Namespace();`, the `Namespace` class is the primary construct. For ESM, direct named import is expected.
• apiElements

  const apiElements = require('api-elements');

  This is the primary CommonJS import pattern, returning an object containing the Namespace class and potentially other utilities.
• ParseResult
  wrong:

  import { ParseResult } from 'api-elements';

  correct:

  import { ParseResult } from 'api-elements/lib/elements';

  Elements like `ParseResult` are typically accessed via `namespace.elements.ParseResult`. Direct importing from a subpath might be necessary for tree-shaking or specific element access in ESM.

Quickstart

This quickstart demonstrates how to initialize the API Elements namespace and create or deserialize API Element ASTs. It shows both parsing a JSON representation and constructing elements programmatically, then accessing properties like the API title.

const apiElements = require('api-elements');
const namespace = new apiElements.Namespace();

// Parsing a JSON Representation of an API Elements tree
const parseResult = namespace.serialiser.deserialise({
  element: 'parseResult',
  content: [
    {
      element: 'category',
      meta: { classes: ['api'] },
      content: [
        { element: 'copy', content: 'My Awesome API' },
        { element: 'resource', content: [] }
      ]
    }
  ]
});

console.log('Deserialized ParseResult element:', parseResult.element);
console.log('API title:', parseResult.api.copy.toValue());

// Creating API Elements directly
const directParseResult = new namespace.elements.ParseResult();
const apiCategory = new namespace.elements.Category();
apiCategory.classes.push('api');
apiCategory.content.push(new namespace.elements.Copy('Another API'));
directParseResult.content.push(apiCategory);

console.log('Directly created ParseResult element:', directParseResult.element);
console.log('Another API title:', directParseResult.api.copy.toValue());