data-engine

@alneas/data-engine

English | 日本語

スキーマ処理、SQL/DDL生成、汎用のデータ・文書ユーティリティ、 グラフ・AI・data-access・storageとの連携を提供する、フレームワーク非依存のMITパッケージです。 engine自身の機能はPublicモノレポのこのパッケージが正本です。

npm install @alneas/data-engine

/schema・/schema/server・/csv・/excel・/workflow・/content・ /content/git-markdown・/edi・/notificationsと、明示的な/integrations/*を利用します。 AIプロトコルはai-core、CRUDはdata-access、ストレージはuniversal-storageから直接importします。 単純な横流しサブパスは初回公開前に削除しました。Oracle Enterprise・DB監査・自律エージェントはPrivateのプレミアム機能です。

日本向け帳票・法務・Excel・EDI規則・初期値は@alneas/business-jpへ移しました。 engineから日本向けpackageへの依存や日本の祝日データはありません。 汎用EDIは通貨・プロファイル、請求額は税率の初期値と丸めを明示し、日付・CSVの書式は選択できます。 直接利用する場合は移動したAPIのimportを更新してください。privateの従来入口・初期値は互換ファサードで維持します。 分離と移行ガイドを参照してください。

利用前にスキーマの仕様・利用条件・制約を確認してください。 JSON Schemaのdraft、AJV/Zodの対応差、DDLと実行環境の制限を説明しています。 TypeScript型だけでは入力検証せず、拡張キーだけでは業務ルール・認可は実装されません。 汎用ユーティリティは税務・法令適合性を保証するものではありません。 Reactに依存しなくても、すべての機能が全browser/edgeで実行できるわけではありません。 サーバー用アダプターには対応runtime・peerが必要です。

APIはJSDoc、機能ガイドはこのリポジトリを正本とし、 ALNEAS Docsが同じworkspaceのMarkdownを直接参照します。 Node >=24、ESM/CJS、NodeNext型を検証します。独立CI・npm公開・初回のlock生成は CONTRIBUTING.mdとRELEASING.mdを確認してください。 Pagesはdocsリポジトリだけが公開します。

日付・Content・OAuth

日付のzone指定は30/45分offsetにも対応します。setTimeは指定先の壁時計時刻でoffsetを解決し、DSTの不存在時刻は例外、重複時刻は早い瞬間を採用します。getTodayDateStringも指定zoneの日付です。業務timezoneを明示してください。

S3ContentAdapterのMarkdownはYAML frontmatterを使い、本文の前後空白・引用符・配列・metadata・tenantIdを保持します。syncはstatus/SEO/metadataを含む永続項目を比較し、updatedAt/lastSyncedAtだけを比較から除きます。indexなし一覧はcursorを追います。同一instanceの変更を直列化し、初回indexに既存文書を残し、削除失敗時はindexを消しません。別instance/process間はホストのlock/CASが必要です。本文とindexは別書込みで、部分失敗の修復・再試行はホストが担当します。

Google OAuthは同一設定のtoken要求を共有します。client/scope変更・clear/logoutでpendingを拒否し、tokenを破棄し、旧callbackを無視します。popup失敗後は再試行できます。実Google認証設定とDOMは利用環境で用意します。

JSON mergeは普通の文字列を含むJavaScript値を受け取り、一度だけJSON化します。JSON化済み文字列を渡すと文字列として保存します。SQLiteはjson(binding)、PostgreSQLはjsonb cast、OracleはFORMAT JSONを使います。path/SQL式は信頼する設定に限定します。SQLiteは実DBでscalar/object/array/nullを検証し、外部DBの実行は利用先の版・接続環境で確認します。

Excelize WASMによるXLSX生成

専用入口/excel/excelizeのExcelizeExcelAdapterで、自前のGoビルドやバックエンドなしに XLSXを生成できます。任意peerのexcelize-wasm@0.1.3を導入し、WASMのファイルパス （Node）または配信URL（ブラウザー）を指定してください。通常のengine・/excelはpeer なしで利用できます。既存のHTTP・自作WASMアダプターも維持します。 Excelガイドに使用例、アセット配置、 対応フィールド、数式・実行環境の制約をまとめています。

任意の連携機能とimportの変更

@alneas/data-engineだけを導入しても、ai-core・task-graph・data-access・ universal-storage・business-jpは入りません。ルート、スキーマ/DDL、CSV・文字コード、 日付、汎用PDF/Excel、金額計算、EDI、カレンダーはこれらを未導入でも使えます。 AJV・Zodなどの汎用ライブラリは通常依存として残します。

入口	利用側で明示的に導入するもの
ルート、/schema/*、/csv、/encoding、/date-utils、/pdf、/excel、/finance、/edi、/google-calendar、/notifications/messages、/notifications/slack、/notifications/google-chat	他のALNEASパッケージは不要
/integrations/ai、既存の/action・/proposal・/generative-ui・/ai-chat・/agent-output	@alneas/ai-core@0.1.0
/integrations/task-graph（計算・DB/HTTP・タスク実行の組み立て）	@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と互換性のある@supabase/supabase-js
/storage・/editor・/notifications	@alneas/universal-storage@0.1.0
/content（入口全体と型定義）	data-accessとuniversal-storage

任意peer依存なので、連携入口のimport・型解決には必要なpeerを明示的に導入してください。 任意とは、未導入で連携機能が動くという意味ではありません。/storageはserver入口です。 browser用storageはuniversal-storageの対応入口を選びます。engine開発時は全peerを 開発依存として入れますが、配布先へ通常依存としては入りません。 AI・グラフの再エクスポートは正本の関数・クラスを共有します。汎用スキーマ検証はengineが AJVを直接使い、ai-coreの検証器を読み込みません。両者の振る舞いは整合性テストで確認し、 関数そのものの同一性は前提にしません。

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

import { createAjvValidator } from '@alneas/data-engine';
import { ActionRegistry } from '@alneas/data-engine/integrations/ai';
// グラフ連携はtask-graphを別途導入してから利用します。
// import { TaskAgentDispatcher } from '@alneas/data-engine/integrations/task-graph';

初回公開前のAPI整理として、ルートのAI・storage・レコードAPIとcontent/editor/notifications 名前空間を上表の専用入口へ移しました。/data-accessのグラフ・エージェントAPIは /integrations/task-graph、提案APIは/proposalまたは/integrations/aiへ変更します。 engine /pdfのresolveSealLabel・印影SVG/data URL生成は @alneas/business-jp/pdf/stamp（/pdfからもexport）へ移しました。 engineから日本向けpackageを任意peerとして読み込む互換入口は作りません。 private app-core/react-toolsの既存名・パスは互換ファサードで維持します。

test:consumerはnpmでengine単独、任意peerを1つずつ追加した環境、全連携環境を 実tarballで検証します。不要なpackageが存在しないこと、Node/BunのESM/CJS実行、 skipLibCheckなしの厳密なNodeNext型解決、基本ルートのbrowser bundleも確認します。 日本向け単独consumerではengine/スキーマ依存がないこと、連携consumerでは明示したengine/business-jpだけであることを確認します。

汎用通知アダプターはconstructor第2引数にNotificationMessagesを受け取り、既定は英語ラベル・通貨記号なしです。承認カードのボタン名も指定できます。日本語の支払・在庫通知と円表示はbusiness-jp /notificationsのjapaneseNotificationMessagesへ移しました。汎用の設定型・初期値入口/notifications/messagesには他のALNEAS packageは不要です。

各クラスは/notifications/slack・/notifications/line・/notifications/google-chatで公開します。createNotificationService(database, organizationId, messages)の第3引数にも表示設定を渡せます。LINE入口は署名検証にuniversal-storageが必要で、Slack/Google Chatの個別入口には他のALNEAS packageは不要です。

UIから独立した値変換・ワークフローの仕様も提供します。

• ファイル連携・削除・補償・検索仕様

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

利用アプリのAI設定

ビルド時に正確なexports・peer依存・CSSパスをdist/ai/package-context.jsonへ生成します。設定のプレビューは次のコマンドで行います。

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

--writeを付けるとAGENTS.mdとCLAUDE.mdの境界付きブロックを更新し、既存の指示を保持します。手順はdist/ai/skills/に同梱します。

AI利用ガイドは配布物の dist/ai/SKILL.md と package-context.json に同梱します。次のコマンドはプロジェクトの指示ファイルへの追記をプレビューします。確認後に --write を付けると既存の指示を保持して反映します。

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