@zavx0z/context

Лёгкая библиотека для типобезопасных контекстов состояния: строгая схема, иммутабельный доступ к значениям, контролируемые обновления и подписки. Часть фреймворка MetaFor (модуль контекста/состояния), при этом может использоваться как самостоятельный пакет.

MetaFor

Библиотека используется во фреймворке MetaFor в качестве слоя контекста/состояния.

Установка

bun add @zavx0z/context
Copy

Быстрый пример

import { Context, types } from "@zavx0z/context"

const ctx = new Context((t) => ({
  name: t.string.required("Гость")({ title: "Имя" }),
  age: t.number.optional()({ title: "Возраст" }),
  isActive: t.boolean.required(true),
  role: t.enum("user", "admin", "moderator").required("user"),
  tags: t.array.required([])({ title: "Теги" }),
}))

// чтение — только через иммутабельный снимок
console.log(ctx.context.name) // "Гость"
console.log(ctx.schema.name.title) // "Имя"

// обновление — возвращает только реально изменённые поля
ctx.update({ name: "Иван", age: 25 }) // { name: "Иван", age: 25 }
ctx.update({ age: 25 }) // {} (ничего не поменялось)
ctx.update({ age: 30 }) // { age: 30 }
ctx.update({ tags: ["важно", "срочно"] }) // { tags: ["важно", "срочно"] }

// подписка на обновления
const off = ctx.onUpdate((updated) => {
  console.log("changed:", updated) // например: { age: 30 }
})
off()
Copy

Ключевые возможности

• Типизированные схемы (string, number, boolean, array, enum).
• Chainable-опции для полей (например, { title: "Имя" }).
• Иммутабельный доступ к значениям: прямое присваивание запрещено.
• Поддержка плоских массивов примитивов с автоматической заморозкой.
• update(values) игнорирует undefined и возвращает только изменённые ключи.
• onUpdate(cb) — подписка передаёт updated: Partial<Values>.
• Заголовки полей доступны через schema.

Снимки и клонирование

// Снимок с метаданными и текущими value
const full = ctx.snapshot

// Сериализуемая схема (без текущих value)
const schemaSnap = ctx.schema

// Восстановление/клонирование
import { ContextClone } from "@zavx0z/context"
const clone = ContextClone.fromSnapshot(ctx.schema)
clone.restoreValues(ctx.context)
Copy

API (кратко)

new Context((types) => schema)

Создает контекст по фабрике схемы. Доступные фабрики: types.string, types.number, types.boolean, types.array, types.enum(...values). У каждой есть .required(default?) и .optional(default?) + chainable-настройки (напр. { title: string }).

Свойства и методы

• context — иммутабельный доступ к значениям (только для чтения).
• schema — сериализованная схема (типы, required, default, title, values?).
• update(values) → Partial<Values> — только реально изменённые поля.
• onUpdate(cb) → () => void — отписка.
• snapshot (геттер) → { [key]: { type, required, default?, title?, values?, value } }.
• ContextClone.fromSnapshot(schema) → ContextClone.
• clone.restoreValues(values).

Экспорты

import { Context, ContextClone } from "@zavx0z/context"
import type { Schema, Values, Snapshot } from "@zavx0z/context"
Copy

Лицензия

MIT © zavx0z