data-engine

@alneas/data-engine

English | 日本語

Framework-independent schema processing, SQL/DDL generation, generic data/document utilities, and composition with graph, AI, data-access and storage packages. MIT. This package in the ALNEAS public monorepo is canonical for the engine’s own features.

npm install @alneas/data-engine

import { createAjvValidator } from '@alneas/data-engine/schema';
const validate = createAjvValidator();
const result = validate({ type: 'object', properties: { name: { type: 'string' } }, required: ['name'], additionalProperties: false }, { name: 'Alice' });

Use /schema, /schema/server, /csv, /excel, /workflow, /content, /content/git-markdown, /edi, /notifications and the explicit /integrations/* entries. Generic CRUD/providers belong to data-access, AI protocols to ai-core and object storage to universal-storage. Simple pass-through entries are removed before initial publication. Oracle Enterprise, DB audits and autonomous agents remain private premium features.

Japanese document/legal/workbook/EDI rules and Japanese defaults moved to @alneas/business-jp. Engine does not depend on that package or Japanese holiday data. Generic EDI factories require an explicit currency/profile context; invoice calculation requires explicit tax/rounding policy; locale/date formatting can be selected. Direct users must migrate moved APIs; private compatibility facades preserve their established paths/defaults. See Package separation and migration.

Read Schema specifications and constraints for JSON Schema dialects, AJV/Zod support differences, DDL limits and execution-host requirements. TypeScript types alone do not validate input. Extensions are not automatic business/authorization rules. Generic document utilities do not establish legal or tax compliance. Framework-free does not mean every operation runs in every browser/edge host; native/server adapters need compatible runtimes and peers.

JSDoc is the API reference. Feature guides live here; the integrated ALNEAS Docs site fetches fixed the same workspace checkout. Node >=24, ESM/CJS and NodeNext types are covered by verification. See CONTRIBUTING.md and RELEASING.md for independent quality/npm CI and the first dependency/registry-lock bootstrap. Only docs deploys Pages.

Dates, content and OAuth lifecycle

Date functions honor explicit IANA zones, including fractional offsets. setTime resolves the target wall-clock time: nonexistent DST times throw; ambiguous times choose the earlier instant. getTodayDateString uses its zone, not the host date. Pass a business timezone explicitly.

S3ContentAdapter Markdown uses YAML frontmatter, preserving exact body whitespace, quotes, arrays, metadata and tenantId. sync compares persisted fields including status/SEO/metadata; updatedAt and lastSyncedAt are bookkeeping only. Fallback listing follows storage cursors. Mutations are serialized within one adapter instance, preserving initial index entries and refusing an index deletion after a failed object deletion. Separate instances/processes require a host lock/CAS; content and index are separate writes, so repair/retry must be handled by the host.

Google OAuth shares one pending token request per configuration. Changing client/scopes or clearing/signing out rejects pending work, drops cached tokens and ignores old callbacks. Popup failures can be retried. Config snapshots are detached. GIS requires a browser DOM and Google setup; tests do not authenticate a real account.

JSON merge helpers receive JavaScript values, including ordinary strings, and serialize once. A serialized JSON-looking string remains a string. SQLite uses json(binding), PostgreSQL casts to jsonb and Oracle SET uses FORMAT JSON. Schema paths/SQL expressions are trusted configuration. SQLite scalar/object/array/null updates are exercised against an actual database; external database behavior requires the target service/version.

XLSX with Excelize WASM

Use ExcelizeExcelAdapter from /excel/excelize for XLSX generation without a custom Go build or backend. Install the optional excelize-wasm@0.1.3 peer and supply its WASM filesystem path (Node) or deployed asset URL (browser). Ordinary engine and /excel imports remain peer-free. Existing HTTP/custom WASM adapters stay available. See the Excel guide for examples, asset deployment, supported workbook fields and formula/runtime limits.

Optional integrations and import changes

Installing @alneas/data-engine alone installs none of ai-core, task-graph, data-access, universal-storage or business-jp. The root entry, schema/DDL, CSV/encoding, dates, generic PDF/Excel, finance, EDI and calendar utilities work without those packages. Runtime dependencies such as AJV and Zod remain required.

Entry	Explicitly install
root, /schema/*, /csv, /encoding, /date-utils, /pdf, /excel, /finance, /edi, /google-calendar, /notifications/messages, /notifications/slack, /notifications/google-chat	No other ALNEAS package
/integrations/ai; existing /action, /proposal, /generative-ui, /ai-chat, /agent-output	@alneas/ai-core@0.1.0
/integrations/task-graph (calculation, DB/HTTP adapters, task dispatcher)	@alneas/task-graph@0.1.0
/excel/excelize	excelize-wasm@0.1.3
/data-access	@alneas/data-access@0.1.0
/data-access/schema-aware	data-access plus compatible @supabase/supabase-js
/storage, /editor, /notifications	@alneas/universal-storage@0.1.0
/content (complete entry and declarations)	data-access and universal-storage

These integrations use optional peers. Install the required peer explicitly before importing its entry, including for TypeScript declaration resolution; optional does not mean an integration works without its implementation. /storage forwards the server adapter entry, so choose universal-storage’s browser entry for browser storage. The engine development environment installs all peers as devDependencies for tests; this does not make them production dependencies. Integration exports preserve canonical AI/graph function and class identities. General schema validation is engine-owned and backed directly by AJV; it no longer imports ai-core’s validator. Both adapters have conformance tests, but their function identities are independent.

npm install @alneas/data-engine @alneas/ai-core

import { createAjvValidator } from '@alneas/data-engine';
import { ActionRegistry } from '@alneas/data-engine/integrations/ai';
// For graph composition, separately install @alneas/task-graph, then use:
// import { TaskAgentDispatcher } from '@alneas/data-engine/integrations/task-graph';

Before the first release, AI, storage and record exports and the content/editor/ notifications namespaces were removed from the engine root. Use the explicit entries above. Graph/agent exports moved from /data-access to /integrations/task-graph; proposals use /proposal or /integrations/ai. Regional resolveSealLabel and fallback seal SVG/data URL functions moved from engine /pdf to @alneas/business-jp/pdf/stamp (also exported by business-jp /pdf). There is no engine compatibility re-export that would introduce a regional peer. Private app-core/react-tools facades retain their previous names and paths.

test:consumer verifies the engine tarball alone with npm, each optional peer in isolation, and the full integration set. It checks absent packages on disk, Node/Bun ESM/CJS execution, strict NodeNext declarations without skipLibCheck, and browser bundling of the generic root. The regional standalone consumer checks that engine/schema dependencies are absent; the integration consumer explicitly installs engine/business-jp only.

Generic notification adapters accept a NotificationMessages policy as their second constructor argument. Defaults use English labels and no implicit currency; localized approval button labels can also be supplied to client card builders. Japanese reminder text/yen presets are exported by business-jp /notifications. The generic policy/type entry /notifications/messages needs no other ALNEAS package.

Provider classes are available from /notifications/slack, /notifications/line and /notifications/google-chat. The createNotificationService(database, organizationId, messages) factory also accepts the policy as its third argument. LINE requires universal-storage for webhook signature support; Slack/Google Chat entries do not require another ALNEAS package.

See schema casting and workflow logic for the framework-free UI-adjacent APIs.

• File records, deletion, compensation and search

Read package boundaries for the current public/premium split and import migration.

Consumer AI setup

The build generates exact exports, peer dependencies and CSS paths in dist/ai/package-context.json. Preview package-scoped project instructions with:

node node_modules/@alneas/data-engine/dist/ai/setup.mjs

Add --write to update bounded blocks in AGENTS.md and CLAUDE.md while preserving host instructions. Package-specific skills live in dist/ai/skills/.

Consumer AI guidance ships in dist/ai/SKILL.md and package-context.json. Preview the package-scoped additions to your project instructions with the following command. Add --write after reviewing the preview; existing instructions are preserved.

node node_modules/@alneas/data-engine/dist/ai/setup.mjs --project .