Stackline Open Source maintained continuation

HAR 1.2 schema validation · MIT

@stackline/har-validator

Validate complete HTTP Archive documents or any of their 18 schema components while keeping the established har-validator@5.1.5 Promise, boolean, callback, and error contracts.

npm install @stackline/har-validator

Keep existing imports unchanged with har-validator: npm:@stackline/har-validator in your dependencies.

01 / Validation model

One schema set, eighteen focused entry points.

The package loads the HAR 1.2 draft-06 definitions from har-schema, registers them with Ajv 6, and compiles lazily with allErrors: true. Validate an entire archive with har(), an HTTP side with request() or response(), or an individual header, cookie, timing, content, cache, page, creator, or browser record.

02 / Quick start

Validate a response.

Promise validators resolve to the exact object passed by the caller. A rejection includes the complete Ajv 6 error array, including dataPath, schema path, keyword, parameters, and message.

const validate = require(
  '@stackline/har-validator'
)

const response = {
  status: 204,
  statusText: 'No Content',
  httpVersion: 'HTTP/1.1',
  headers: [], cookies: [],
  content: { size: 0, mimeType: 'text/plain' },
  redirectURL: '', headersSize: -1, bodySize: 0
}

await validate.response(response)

03 / Public API

Three call forms, one schema result.

Open the complete API reference →

validator(data) → Promise

Root Promise namespace

All 18 enumerable validators preserve upstream property order, falsy-input normalization, resolution identity, rejection timing, and complete Ajv error records.

lib/async.validator(data[, callback])

Boolean or callback

Without a callback, returns a synchronous boolean. With one, invokes (error, valid) synchronously and returns the callback's own value.

new HARError(errors)

Stable failure shape

Exposes name, message, errors, and the upstream stack shape. The corrected isolated prototype remains an Error.

harlogentryrequestresponsecontentcachetimings

04 / Exact semantics

Compatibility is measured at the result boundary.

The implementation is compared against the immutable upstream artifact and an isolated Ajv 6.12.3 golden result set. The maintained dependency stays on Ajv 6 to retain dataPath-based errors and HAR draft-06 behavior. The Node.js 6.17.1 floor applies to CommonJS; ESM is additive on runtimes and build tools that support it.

The only intentional CommonJS correction is the HARError prototype: unrelated ordinary errors no longer satisfy instanceof HARError. Constructor, stack, enumerable shape, and direct-call behavior remain upstream-compatible.

  1. 01
    normalizeFalsy input becomes an empty object
  2. 02
    compile lazilyDraft-06 and all HAR schemas registered once
  3. 03
    validateAjv reports every schema error
  4. 04
    resolve or rejectSame reference or stable HARError
  5. 05
    preserve deep APIBoolean and callbacks remain synchronous

05 / Browser use

Bundle the shared graph by default.

Open the browser-bundler example →
Recommended

Normal root and deep imports

import validate from
  '@stackline/har-validator'
import HARError from
  '@stackline/har-validator/lib/error'

Browser-aware bundlers receive browser-compatible sources in one graph, so rejected errors retain identity with the deep constructor.

Root only

Self-contained browser entry

import validate from
  '@stackline/har-validator/browser'

The additive CJS/ESM bundle exposes only the Promise namespace. Ajv performs runtime code generation; review strict Content Security Policy requirements before adoption.

06 / Migration

Choose the size of your diff.

Full migration checklist →
Lowest change

Alias the dependency

"har-validator":
  "npm:@stackline/har-validator@1.0.0"

Existing root, lib/promise, lib/async, and lib/error imports stay unchanged. Commit the manifest and lockfile together.

Explicit adoption

Use the scoped name

import validate, { response }
  from '@stackline/har-validator'

Real ESM, named exports, TypeScript declarations, conditional exports, and browser bundles are additive to the preserved CommonJS contract.

Re-test in your application valid HAR fixturescomplete error arraysfalsy inputcallback timingdeep importsbrowser CSP

07 / Trust boundary

Schema-valid is not safe or authentic.

The validators check HAR 1.2 structure. They do not parse JSON, sanitize header or body content, approve URLs, verify that an exchange occurred, reconcile sizes and timings, or bound attacker-controlled work. Apply byte, depth, entry-count, and time limits before validating untrusted archives.

Treat URLs, cookies, headers, query strings, post data, and response text as untrusted even after validation. In browsers, Ajv's runtime compilation may be rejected by a Content Security Policy that disallows dynamic code generation.

Read the complete security and reporting boundary →

08 / Reference files

The contract is inspectable.

READMEInstall and core usage API referenceValidators, errors, deep entries CompatibilityPreserved and corrected behavior MigrationAlias, scoped imports, rollback LicensesExact seven-component graph CommonJS examplePromise creator validation ESM exampleNamed Promise validator Browser exampleShared HARError graph SecurityReporting and safe-use boundary Machine referenceCompact complete contract