仕様・利用条件・制約

仕様・利用条件・制約

責務とimport

ルートはCRUD共通型、リソースサービス、検索補助、キャッシュ識別、注入式の小数変換を 提供します。DBアダプターは個別サブパスからimportします。ルートの利用にDB SDKは不要です。 Supabaseの型定義を利用するときは、実際の @supabase/supabase-js も導入します。 DB接続・テーブル・認証情報・APIサーバーのデプロイはアプリ側が担当します。 importしただけでは接続しません。

DataAccessAdapterはレコードとコレクション、StorageAdapterはファイルとバイナリを 扱います。両パッケージ間に依存はありません。添付ファイル処理はサービスのcallbackで 接続でき、アップロードとレコード更新の一括トランザクションは提供しません。

DBごとの対応範囲

入口	必要なもの・制約
/sqlite	注入したSqliteDriver。prepare形式はcreateSqliteDriverで変換可能
/d1	アプリのD1 binding。外部のCloudflare資格情報を自動取得しない
/supabase	Supabase 2.x client、PostgRESTと既存のDBリレーション
/supabase-graphql	Supabase client、pg_graphql、有効なGraphQLのフィールド指定
/mongodb	このパッケージのMongo HTTPプロトコルを実装したサーバー。MongoDBへ直接接続するdriverではない
/convex	注入したclientとquery/mutation参照。Reactへの依存なし
/neon	queryFnの注入、またはNeon serverless 1.xとサーバー内の接続文字列

Filterは Record<string, unknown> で、JSON Schemaバリデーターではありません。 外部入力から利用する場合、アプリ側で対象リソース・フィールド・演算子を許可リストで 制限し、入力サイズ・取得件数・クエリコスト・権限を検証します。SQL識別子にはアプリで 管理した値を使い、外部入力をそのまま渡さないでください。

SQLite/D1が対応する比較は $eq・$neq・$lt・$lte・$gt・$gte・$in・$nin です。nullの一致・不一致はIS NULL/IS NOT NULLへ変換します。オブジェクト・配列の 自動JSON化、REGEXP、汎用populate/join、論理 $or/$and は提供しません。 今回対象のSQL・ORDS・Supabaseアダプターも未対応演算子を例外にします。 アプリ側の入力・認可検証も維持し、未検証の条件をそのまま転送しないでください。

検索補助createTableSearchHandlerは $or と $ilike を生成するので、両方に対応する バックエンドだけで利用します。共通型は同じ機能・結果を全DBで保証するものではありません。 signal、projection、populate、ページネーション、件数取得、一括操作の対応は実装ごとに異なります。 任意メソッドの有無を確認し、一括操作の失敗時に全件ロールバックされるとは想定しないでください。

createResourceServiceのdefaultQueryOptionsはfindに適用し、呼び出し時の指定を優先します。 他のメソッドは呼び出し時のoptionsを転送します。bulkCreate/bulkUpdateはアダプターの 対応メソッドがなければ例外になります。スキーマ検証・認可・DB migrationは自動実行しません。

認証・キャッシュ・データ変換

DB接続文字列、DBパスワード、特権キーはサーバー内で扱います。token callbackやfetchの 注入は通信の拡張点で、認可そのものではありません。API・DB側の権限とテナント境界は アプリが実装・検証します。

キャッシュ識別は通常アダプターのインスタンス単位です。同じcacheScopeを明示すると 別インスタンス間で共有を意図した扱いになります。ユーザー・ロール・テナントの境界が 変わるときはscopeも変更し、認証情報そのものをキーに含めません。 このパッケージはReact Contextやキャッシュクライアントを提供しません。

スキーマ連携にはengineの /integrations/supabase を利用できます。依存は engine → data-accessの一方向です。data-access自身はAJV/Zodを導入しません。 BigNumberDataAccessAdapterは互換の小数型コンストラクターとフィールド設定を注入します。 桁数・丸め・JSONでの表現方法はアプリの仕様に合わせて検証してください。

添付メタデータは汎用型で、ResourceServiceの追加型引数によりアプリで拡張できます。 案件明細ID/コードはprivate app-core側に残しています。ファイルアップロードとDB更新の 片方だけが失敗した場合の後処理・再試行はアプリ側が担当します。

検証とドキュメント公開

bun run verifyでテストを含む型検査、依存境界、単体/モック、実メモリ内SQLite、 ESM/CJSビルド、Node/Bunのtarball consumer、NodeNext型解決、共通APIのブラウザbundleを 検証します。実DBへの認証、クラウド設定、本番の権限はモックテストの対象外です。

このガイドの正本はパッケージのリポジトリです。apps/docsが同じworkspaceから 取得して統合公開します。ローカルプレビューは明示的な開発モードで、公開済み版の検証とは区別します。

検証したTypeScript・SDKの組合せ

SDKに依存しない配布入口はTypeScript 6.0.3で、Nodeのambient型を読み込まず検証します。 実際のSupabase 2.118 SDKと全provider入口はTypeScript 5.7.3で、skipLibCheckを使わず 厳密に検証します。Supabase auth-js 2.118のWebAuthn型には、TypeScript 6.0.3のDOM型 PublicKeyCredential.toJSONとの不整合があります。このSDK版とTS 6の厳密な組合せは 対応済みと扱いません。SDK・compiler更新時はこの組合せを再検証して表を更新します。

未対応filter/operator・不正operand・undefined/非有限数値・空の論理groupは実行前に例外になり、条件を捨てて実行しません。Neonは比較/in/nin/regex/ilike/非空and/or、Oracle DirectとORDSは比較/in/nin/regex（論理group不可）、Supabase RESTは比較/in/nin/regex（部分一致ilike）/ilike/非空and（or不可）、GraphQLは比較/in/POSIX regex（nin・論理group不可、null比較はis enum）です。SQLのnull比較はIS NULL/IS NOT NULL、空inは0件、空ninは除外なしです。Oracle Directは単純識別子だけ、collectionのschema指定は区切って引用します。Neonもschema名を別々に引用します。Direct/Neonのlimit/skipは非負の安全な整数です。

Oracle Duality ViewもDirect SQLと同様に不正filterを実行前に拒否します。比較・リスト・regex演算子に対応し、論理グループは拒否します。nullの等価・不等価はIS NULL/IS NOT NULLです。collectionはschema修飾可能で、column・JSON path・sortは[A-Za-z_][A-Za-z0-9_]*の名前付きsegmentに限定します。配列添字・生SQL・任意JSON path式は非対応です。limit/skipは非負の安全な整数とし、利用側でもresource名をallowlistで制限してください。Direct create/update/replaceは列名と別のbind名を生成し、target_id・ret_id・value_0等も通常の列として保持します。空のcreate/updateデータは拒否します。両Oracleのcountは0件を数値0として返します。対象DB版・権限の実接続検証は利用環境で実施してください。