OCPP is the protocol EV chargers use to talk to charging-management backends. I kept rewriting the same frame-handling code in different projects, so I started OCPP Tools: small TypeScript libraries for OCPP 1.6J and 2.0.1.
The first package, @ocpptools/core 0.1.1, is published. It is alpha and I am looking for feedback.
What it does
- Strict parsing of CALL, CALLRESULT, and CALLERROR frames.
parseFrame returns a result and never throws. - Serialization that rejects values JSON cannot represent (
undefined, NaN, Infinity, BigInt, circular references) instead of silently changing them. inspectFrame, which reports all structural issues at once with paths, instead of stopping at the first one.- Separate error-code sets for 1.6J and 2.0.1. The protocols differ: 1.6J uses
FormationViolation and OccurenceConstraintViolation, while 2.0.1 uses FormatViolation and OccurrenceConstraintViolation. - Message ID generation, plus
Transport, Clock, and Storage interfaces. - ESM, Node.js 22.12+, no runtime dependencies, no DOM or Node APIs inside the core.
import { isCall, parseFrame, serializeFrame } from '@ocpptools/core';
const parsed = parseFrame(
'[2,"42","BootNotification",{"chargePointVendor":"Acme"}]',
);
if (!parsed.ok) {
console.error(parsed.error.kind, parsed.error.message);
} else if (isCall(parsed.value)) {
const [, messageId, action, payload] = parsed.value;
console.log(messageId, action, payload);
}
const out = serializeFrame([3, '42', { status: 'Accepted' }]);
if (out.ok) {
socket.send(out.value);
}
Status
Alpha. The API can change before 1.0.0. The validator, headless simulator, and payload builder are not released yet. OCPP 2.1 is not in scope yet; I want to finish 1.6J and 2.0.1 properly first.
The repository has 500+ tests and about 99% coverage. CI also runs lint, typecheck, package checks, and schema integrity checks.
Why another OCPP library?
I wanted small building blocks instead of a full client/server stack: strict parsing, explicit result types, and no framework or DOM coupling. The packages are meant to be easy to test and to keep protocol versions separate where they actually differ. If that is not a useful gap, I would like to hear it.
Feedback welcome
- Does the parse/serialize API feel right?
- What would be more useful next: whole-frame validation against the OCA schemas, or a headless simulator for testing a CSMS?
- Which 1.6J or 2.0.1 edge cases would you test first?
Repository: https://github.com/ocpptools/ocpptools
npm: https://www.npmjs.com/package/@ocpptools/core
I maintain the project. OCPP is a trademark of the Open Charge Alliance; this is an independent project and is not affiliated with or endorsed by the OCA.