@anclatechs/serde-js

@anclatechs/serde-js

A context-aware, declarative serialization and validation framework for JavaScript.

serde-js lets you define one schema that can:

- validate user input (writes)
- safely serialize output (reads)
- enforce conditional logic via context
- support nested objects and arrays
- aggregate errors with precise paths

Inspired by Django REST Framework, Zod, and Joi — but designed to stay lightweight, explicit, and extensible.

---

Table of Contents

- Installation
- Core Concepts
- Quick Start
- Fields
- Serializer
- Read vs Write Modes
- Context-Aware Rules
- Validation
- Nested Serializers
- ArrayField
- Error Handling
- Schema Introspection
- Advanced Patterns
- Design Philosophy

---

Installation

``bash
npm install @anclatechs/serde-js
`

`js
const {
Serializer,
CharField,
NumberField,
IntegerField,
BooleanField,
DateTimeField,
DateField,
EmailField,
UrlField,
ArrayField,
ObjectField,
JsonField,
} = require("@anclatechs/serde-js");
`

---

Core Concepts

$3

A single Serializer definition can:

- validate input (e.g. signup, update)
- serialize output (API responses)
- behave differently based on context

No duplicate schemas. No conditionals scattered across controllers.

---

$3

Each field:

- knows whether it is required
- can be optional or have defaults
- supports custom validators
- can be read-only or write-only
- can be conditionally included

---

$3

Context is an arbitrary object you pass at runtime. Example:

`js
{
mode: "input" | "output",
isSignup: true,
userRole: "admin"
}
`

Fields and validators can react to it.

---

Quick Start

`js
const UserSerializer = new Serializer({
name: new CharField(),
age: new IntegerField().optional(),
email: new EmailField(),
});

const result = UserSerializer.serialize({
name: "Ada",
age: 30,
email: "ada@example.com",
});

console.log(result.data); // serialized output
console.log(result.errors); // error mapping
console.log(result.isValid()) // boolean status for any available error
console.log(result.verboseErrorList()) // simplified, "verbosed" errors data retunred as an Array of object; accessible via .message.
`

---

Fields

$3

All fields inherit from Field.

Supported features:

`js
new Field()
.optional()
.default(value)
.validate(fn)
.onlyIf((ctx) => boolean)
.readOnly()
.writeOnly();
`

CharField, in addition to the validate function, also provide helper methods:

`js
.enumOptions([])
.minLength(num)
.maxLength(num)
`

NumberField and IntegerField also both support the .min() and .max() helper methods.

---

$3

| Field | Description |
| --------------- | -------------- |
| CharField | String values |
| NumberField | Any number |
| IntegerField | Integer-only |
| BooleanField | Boolean |
| DateTimeField | JS Date (ISO) |
| DateField | Date-only |
| EmailField | Email string |
| UrlField | URL string |
| ArrayField | Arrays |
| ObjectField | Nested structured objects |
| JsonField | dynamic JSON object |

---

Serializer

$3

`js
const UserSerializer = new Serializer(schema, options);
`

$3

`js
{
many?: boolean // expect an array of objects
}
`

---

Read vs Write Modes

$3

Often:

- some fields should only be accepted (password)
- some should only be returned (id, timestamps)

$3

`js
const UserSerializer = new Serializer({
id: new IntegerField().readOnly(),
email: new EmailField(),
password: new CharField().writeOnly(),
});
`

#### Input (write)

`js
UserSerializer.serialize(req.body, { mode: "input" });
`

#### Output (read)

`js
UserSerializer.serialize(user, { mode: "output" });
`

---

Context-Aware Rules

$3

Conditionally include a field.

`js
role: new CharField().onlyIf((ctx) => ctx.userRole === "admin");
`

$3

`js
password: new CharField().onlyIf((ctx) => ctx.isSignup);
`

If the condition fails, the field is:

- not required
- not validated
- not serialized

---


Default Values

The Field.default() method allows you to provide a value when the input does not specify one.

It can be either:

$3

`js
const UserSerializer = new Serializer({
name: new CharField().default("Ada"),
});
`

$3

You can compute the default value based on other fields in the serializer or context:

`js
const UserSerializer = new Serializer({
name: new CharField(),
age: new IntegerField(),
ageInTwoYears: new IntegerField().default((_, root, ctx) => root.age * 2).readOnly(),
});
`

#### Parameters of the default function

| Parameter | Description |
| --------- | ---------------------------------------------------------------------------------------------------------------------- |
| value | The input value for this field. If the input is missing, it will be undefined. May be ignored and represented as _. |
| root | The partially built serialized object. Lets you reference other fields in the same serializer. |
| ctx | Optional context object passed to serialize(input, context). Useful for user info, request metadata, etc. |

⚠️ Order matters: The field you reference in root (e.g., age) must appear before the dependent field (ageInTwoYears) in the schema.

---

Validation

$3

`js
age: new IntegerField().validate((v) => v >= 18 || "Must be 18+");
`

Validators return:

- true → pass
- false or string → fail

---

$3

`js
const min = (n) => (v) => v >= n || Must be ≥ ${n};
const minLength = (n) => (v) => v.length >= n || Min length ${n};
`

`js
password: new CharField().validate(minLength(8));
`

---

Nested Serializers

$3

`js
const AddressSerializer = new Serializer({
street: new CharField(),
city: new CharField(),
});

const UserSerializer = new Serializer({
name: new CharField(),
address: new ObjectField(AddressSerializer),
});
`

Nested errors are merged automatically:

`
address.city: Field is required
`

---

ArrayField

$3

`js
tags: new ArrayField(new CharField());
`

$3

`js
posts: new ArrayField(PostSerializer);
`

Each item is validated independently with full error paths:

`
posts[2].title: Field is required
`

---

Error Handling

Errors are aggregated on the serializer:

`js
serializer.errors;
`

Example:

`js
{
"email": "Invalid EmailField",
"address.city": "Field is required",
"tags[1]": "Invalid CharField"
}
`

No exceptions. Full visibility.

---

Schema Introspection

$3

`js
UserSerializer.describe();
`

Returns:

`js
{
email: {
type: "EmailField",
required: true
},
tags: {
type: "ArrayField",
child: "CharField"
}
}
`

Useful for:

- documentation
- form generation
- schema inspection

---

Advanced Patterns

$3

`js
password: new CharField(),
confirmPassword: new CharField().validate((v, ctx) =>
v === ctx.password || "Passwords do not match"
)
`

$3

`js
salary: new NumberField().onlyIf((ctx) => ctx.userRole === "admin");
`

$3

`js
new CharField().optional().onlyIf((ctx) => ctx.isUpdate);
`

---

Design Philosophy

- Explicit over magical
- One schema, many flows
- Context drives behavior
- Errors should be precise
- Composition over inheritance

serde-js` is intentionally unopinionated about:

- HTTP frameworks
- Databases
- ORMs

It fits cleanly into Express, Fastify, NestJS, or serverless setups.

---

Final Note

This library is intentionally small but powerful; supporting optional fields, default values, custom validators, aggregated error reporting, and context-aware serialization. Fields are required by default, your may define defaults or validation rules, and can dynamically include or validate data based on your preferred runtime context. Validation errors are collected and returned in a structured, predictable format suitable for APIs and batch processing.

If you understand how context flows, you can model:

- signup
- updates
- admin overrides
- read/write separation

…without ever duplicating schemas.

📜 License

MIT — use it, hack it, ship it.

Happy building 🚀