apg-lite

library1.0.5jsnpmunverified

apg-lite is a lightweight JavaScript parser for ABNF (Augmented Backus-Naur Form) grammars, supporting a simplified subset of SABNF operators. It functions strictly as a parser, requiring grammar objects to be pre-generated using `apg-js` (version 4.3.0 or higher) with its `--lite` option. Currently at version 1.0.5, it parses only JavaScript strings, a key distinction from `apg-js` which handles arbitrary arrays of positive integers. The library retains only User-Defined Terminals (UDT), positive look-ahead (AND), and negative look-ahead (NOT) operators from the SABNF superset. It offers simplified AST manipulation, parse tree tracing for debugging, and statistics collection for profiling, all encapsulated within a single ECMAScript Module (ESM) compatible JavaScript file. The package is actively maintained, with a release cadence driven by bug fixes and minor enhancements, as demonstrated by recent updates to its robust, dependency-free URI parser.

serialization

npm install apg-lite

github ↗package ↗

INSTALL

IMPORT

SIG · APG-LITE

apg-lite

serializationjavascriptv1.0.5

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Parser

✓ import { Parser } from 'apg-lite/lib/parser'

✗ const { Parser } = require('apg-lite/lib/parser')

The primary parser module is ESM-only and typically exports a class or factory function like 'Parser'.

UriParser

✓ import { UriParser } from 'apg-lite/uri-app/UriParser'

✗ const { UriParser } = require('apg-lite/uri-app/UriParser')

The specialized URI parser is a self-contained ESM module provided as an example, suitable for direct import.

webParserScript

✓ <script src="./node_modules/apg-lite/lib/web-parser.js"></script>

✗ import { Parser } from 'apg-lite/lib/web-parser'

`web-parser.js` is designed for direct inclusion via a `<script>` tag in web pages, making global objects available rather than named ESM exports for direct import.

Demonstrates how to import and use the self-contained UriParser to parse various URI strings, logging success or failure with the resulting AST.

import { UriParser } from 'apg-lite/uri-app/UriParser'; const uriStrings = [ 'http://user:pass@host:80/path?query#fragment', 'mailto:john.doe@example.com', 'ftp://ftp.example.com/dir/file.txt', '//example.org/schema-relative/path', 'data:text/plain;base64,SGVsbG8sIFdvcmxkIQ==', '' // Empty string for demonstration ]; console.log('Parsing various URI strings:'); uriStrings.forEach(uriStr => { try { const parser = new UriParser(uriStr); const result = parser.parse(); if (result.success) { console.log(`\nURI: '${uriStr}'`); console.log(' Parse successful. Result:', JSON.stringify(result.ast, null, 2)); } else { console.error(`\nURI: '${uriStr}'`); console.error(' Parse failed. Error:', result.error); } } catch (e) { console.error(`\nError parsing URI '${uriStr}':`, e.message); } });

Debug

Known issues

breakingapg-lite is a parser *only*. It does not generate grammars. Grammar objects must be pre-generated using `apg-js` (v4.3.0+) with the `--lite` option. Directly feeding ABNF definitions to `apg-lite` will not work.

fix

Use `apg-js` (version 4.3.0 or higher) with its `--lite` option to generate the grammar object files, then import those generated objects into your `apg-lite` application.

affects: >=1.0.0

breakingapg-lite only parses JavaScript strings. It does not support parsing arbitrary arrays of positive integers, a feature available in the full `apg-js` library.

fix

Ensure all input for `apg-lite` parsers is a JavaScript string. If you require parsing integer arrays, consider using the full `apg-js` library instead.

affects: >=1.0.0

breakingapg-lite supports only three SABNF superset operators: User-Defined Terminals (UDT), positive look-ahead (AND), and negative look-ahead (NOT). Grammars utilizing other SABNF operators (e.g., semantic validation, case-sensitive/insensitive string literals) will not be correctly processed or will fail.

fix

Simplify your ABNF/SABNF grammars to rely solely on the supported UDT, AND, and NOT operators for use with `apg-lite`. For full SABNF feature support, use `apg-js`.

affects: >=1.0.0

gotchaVersion 1.0.5 fixed a critical bug in the URI grammar definition where previous versions incorrectly allowed empty strings for IPv4 octets. Relying on pre-1.0.5 URI parsing behavior may lead to incorrectly validated URIs.

fix

Update to `apg-lite` version 1.0.5 or higher to ensure correct and RFC-compliant URI parsing behavior, especially if using the `UriParser`.

affects: <1.0.5

Errors

Common errors & fixes

ReferenceError: require is not defined

Attempting to use CommonJS `require()` in an ECMAScript Module (ESM) context or a browser where `apg-lite` is loaded via standard script tags.

fix

For Node.js, ensure your project or file is configured for ESM (e.g., `"type": "module"` in `package.json` or using `.mjs` file extensions) and use `import` statements. For browsers, use `<script src="..."></script>` for `web-parser.js`.

SyntaxError: Cannot use import statement outside a module

Using an `import` statement in a Node.js file that is treated as CommonJS (e.g., `.js` file without `"type": "module"` in `package.json`).

fix

Either change your Node.js project to use ESM by adding `"type": "module"` to `package.json`, or rename the file to have a `.mjs` extension. Alternatively, if bundling for a browser, ensure your bundler supports ESM.

TypeError: Parser is not a constructor

Incorrectly importing or accessing the `Parser` class/function from `apg-lite`, or attempting to use a CommonJS `require()` result as a constructor when it's an ESM export.

fix

Verify the correct ESM import path (e.g., `import { Parser } from 'apg-lite/lib/parser'`) and ensure your environment supports ESM. If `Parser` is a factory function, use `Parser()` instead of `new Parser()`.

Upgrade

Version history

1.0.5latest on npm

Audit

Dependencies

No dependency data recorded yet.

Agent activity

28 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/ldthomas/apg-lite ↗

packagehttps://www.npmjs.com/package/apg-lite ↗