@orizm/cli 3.1.0 → 3.3.0-beta.0

package/dist/docs/features/schema/database.md

@@ -0,0 +1,419 @@
+<!-- source: docs/src/app/features/schema/database/page.mdx -->
+
+# データベース
+
+スキーマを通してデータベースの構造を定義します。
+
+## テーブル
+
+テーブルはデータを保存するための入れ物です。  
+Excelのように行と列で構成され、行はレコード、列はカラムと呼ばれます。  
+以下のテーブルは4つのカラムを持ち、3つのレコードが保存されています。
+
+| id  | name   | description                                                                 | color  |
+| --- | ------ | --------------------------------------------------------------------------- | ------ |
+| 1   | Apple  | It is said, “An apple a day keeps the doctor away.”                         | red    |
+| 2   | Orange | Born in the Assam region of India.                                          | orange |
+| 3   | Grape  | It is said that there are more than 1,000 varieties of grapes in the world. | purple |
+
+テーブルを設計する際には、カラムの定義が重要です。カラムによってテーブルのデータ構造が決まります。
+
+スキーマでは、以下のようにテーブルを定義します。`columns` プロパティでカラムの定義を行います。カラムを定義する際は `type` プロパティでデータ型を指定します。
+
+```ts copy filename="orizm.config.ts" showLineNumbers
+import { defineConfig } from "@orizm/cli/config";
+
+export default defineConfig({
+  tables: {
+    blog: {
+      columns: {
+        title: {
+          type: "string",
+        },
+        body: {
+          type: "string",
+        },
+      },
+    },
+  },
+});
+```
+
+## データ型
+
+以下のデータ型を使用できます。
+
+- [string](#string)
+- [number](#number)
+- [boolean](#boolean)
+- [json](#json)
+- [reference](#reference)
+- [module](#module)
+- [module-array](#module-array)
+- [storage](#storage)
+
+### string
+
+テキストデータを扱う際に使用します。
+
+以下のオプションが設定できます。
+
+| オプション | 説明                                           | 型      | デフォルト |
+| ---------- | ---------------------------------------------- | ------- | ---------- |
+| required   | 必須項目であることを示します。                 | boolean | false      |
+| readonly   | 読み取り専用であることを示します。             | boolean | false      |
+| pattern    | 正規表現を用いて文字列のパターンを指定します。 | string  | -          |
+| minLength  | 文字列の最小長を指定します。                   | number  | -          |
+| maxLength  | 文字列の最大長を指定します。                   | number  | -          |
+| default    | デフォルト値を指定します。                     | string  | -          |
+
+```ts copy
+{
+  type: "string",
+  required: true,
+  readOnly: true,
+  pattern: "^[a-zA-Z]+$",
+  minLength: 1,
+  maxLength: 255,
+  default: "default value",
+}
+```
+
+TypeScriptの型は `string` です。
+
+### number
+
+数値データを扱う際に使用します。
+
+以下のオプションが設定できます。
+
+| オプション | 説明                               | 型      | デフォルト |
+| ---------- | ---------------------------------- | ------- | ---------- |
+| required   | 必須項目であることを示します。     | boolean | false      |
+| readonly   | 読み取り専用であることを示します。 | boolean | false      |
+| default    | デフォルト値を指定します。         | number  | -          |
+
+```ts copy
+{
+  type: "number",
+  required: true,
+  readOnly: true,
+  default: 0,
+}
+```
+
+TypeScriptの型は `number` です。
+
+### boolean
+
+真偽値を扱う際に使用します。
+
+以下のオプションが設定できます。
+
+| オプション | 説明                               | 型      | デフォルト |
+| ---------- | ---------------------------------- | ------- | ---------- |
+| required   | 必須項目であることを示します。     | boolean | false      |
+| readonly   | 読み取り専用であることを示します。 | boolean | false      |
+| default    | デフォルト値を指定します。         | boolean | -          |
+
+```ts copy
+{
+  type: "boolean",
+  required: true,
+  readOnly: true,
+  default: false,
+}
+```
+
+TypeScriptの型は `boolean` です。
+
+### json
+
+JSONデータを扱う際に使用します。
+
+以下のオプションが設定できます。
+
+| オプション | 説明                               | 型      | デフォルト |
+| ---------- | ---------------------------------- | ------- | ---------- |
+| required   | 必須項目であることを示します。     | boolean | false      |
+| readonly   | 読み取り専用であることを示します。 | boolean | false      |
+| default    | デフォルト値を指定します。         | object  | -          |
+
+```ts copy
+{
+  type: "json",
+  required: true,
+  readOnly: true,
+  default: {},
+}
+```
+
+TypeScriptの型は `unknown` です。  
+ 定形データを扱う場合は、より型安全に扱うことのできる [module](./database.md#module) や [module-array](./database.md#module-array) の利用も検討してください。
+
+### reference
+
+他のテーブルのレコードを参照するためのデータ型です。リレーショナルデータベースにおける外部キーのように使用されます。
+
+以下のプロパティを設定する必要があります。
+
+| オプション  | 説明                                                           | 型                                    |
+| ----------- | -------------------------------------------------------------- | ------------------------------------- |
+| tableName   | 参照するテーブルの名前を指定します。                           | string                                |
+| includeName | 参照先のレコードにアクセスするためのプロパティ名を指定します。 | string                                |
+| onDelete    | 参照先のレコードが削除された際の挙動を指定します。             | "cascade" \| "set null" \| "restrict" |
+
+reference型のカラムではSDKを利用してデータを取得する際に `include` プロパティを使用して参照先のデータを結合することができます。`includeName` で参照先のデータにアクセスするためのプロパティ名を指定します。これにより参照先のデータを取得する際に、より直感的な名前でアクセスできます。
+
+例えば以下のようにカラムを定義した場合、`authorId` で著者IDにアクセスできます。`includeName` で `author` と指定しているため、 `include` している場合は `author` で著者のデータにアクセスできます。
+
+```ts copy
+/*
+ * テーブル定義
+ *
+ * article: {
+ *   columns: {
+ *     authorId:{
+ *       type: "reference",
+ *       tableName: "author",
+ *       onDelete: "set null",
+ *       includeName: "author",
+ *     }
+ *   }
+ * }
+ */
+
+const data = client.tables.article.get(articleId, {
+  include: {
+    author: true,
+  },
+});
+
+// data.authorId で author の ID にアクセス可能
+console.log(data.authorId);
+// data.author で author のデータにアクセス可能
+console.log(data.author);
+```
+
+`onDelete` プロパティは以下の値から選択できます。
+
+- **cascade**: 参照先のレコードが削除された際、自身のレコードも削除します。
+- **set null**: 参照先のレコードが削除された際、カラムの値を `null` に設定します。
+- **restrict**: 参照先のレコードの削除を拒否し、エラーとして処理します。
+
+reference型のカラムには以下のオプションが設定できます。
+
+| オプション | 説明                                                                               | 型      | デフォルト |
+| ---------- | ---------------------------------------------------------------------------------- | ------- | ---------- |
+| required   | 必須項目であることを示します。onDelete が "set null" の場合、true にはできません。 | boolean | false      |
+| readonly   | 読み取り専用であることを示します。                                                 | boolean | false      |
+
+```ts copy
+{
+  type: "reference",
+  tableName: "referenceTable",
+  onDelete: "cascade",
+  required: true,
+  readOnly: true,
+  includeName: "refCol",
+}
+```
+
+TypeScriptの型は、`string | undefined` になり、参照先レコードのIDが格納されます。  
+`includeName` で指定したプロパティは、参照先のテーブルの型(T)を持つ `T | undefined` になります。
+
+### module
+
+テーブルモジュールをカラムに対して 1:1 の関係で紐づける際に使用します。詳細は [テーブルモジュール](./table-module.md) を参照してください。
+
+以下のプロパティを設定する必要があります。
+
+| オプション | 説明                           | 型     |
+| ---------- | ------------------------------ | ------ |
+| moduleName | モジュールの名前を指定します。 | string |
+
+```ts copy
+{
+  type: "module",
+  moduleName: "moduleA",
+}
+```
+
+TypeScriptの型は、テーブルモジュールのカラム定義に従った型になります。
+
+### module-array
+
+テーブルモジュールをカラムに対して 1:N の関係で紐づける際に使用します。詳細は [テーブルモジュール](./table-module.md) を参照してください。
+
+以下のプロパティを設定する必要があります。
+
+| オプション | 説明                           | 型     |
+| ---------- | ------------------------------ | ------ |
+| moduleName | モジュールの名前を指定します。 | string |
+
+```ts copy
+{
+  type: "module-array",
+  moduleName: "moduleA",
+}
+```
+
+TypeScriptの型は、テーブルモジュールのカラム定義に従った型を持つ配列になります。
+
+### storage
+
+ファイルを扱う際に使用します。
+
+storage型カラムとバケットはファイルを扱う点で似ていますが異なる点があります。バケットはシンプルなファイル置き場であるのに対し、storage型カラムはファイルをレコードに紐づけて扱います。例えば、ブログ記事にサムネイル画像を設定する場合、storage型カラムを使用して画像ファイルをレコードに紐づけることができます。
+
+レコードが削除された場合、ファイルは30日後に自動で削除されます。削除前であれば、[編集履歴の管理機能](../history.md) を利用して復元することも可能です。
+
+以下のオプションが設定できます。
+
+| オプション | 説明                               | 型      | デフォルト |
+| ---------- | ---------------------------------- | ------- | ---------- |
+| readonly   | 読み取り専用であることを示します。 | boolean | false      |
+
+```ts copy
+{
+  type: "storage",
+  readOnly: true,
+}
+```
+
+TypeScriptの型は `StorageItemType` です。
+
+```ts copy
+type StorageItemType = {
+  /**
+   * ストレージアイテムを一意に識別するための識別子です。
+   * アップロードAPIから取得したハンドルをテーブルに書き込むことでリンクが確立され、
+   * アクセス可能なURLが発行されます。このフィールドは書き込み専用です。
+   */
+  handle?: string | null;
+  /**
+   * ストレージアイテムの公開URLです。
+   * 一般公開用に認証なしでアクセス可能なURLが発行されます。
+   */
+  _publicUrl?: string;
+  /**
+   * ストレージアイテムの保護されたURLです。
+   * API呼び出し元に対して署名されたURLです。
+   */
+  _protectedUrl?: string;
+  _attributes?: {
+    /** ファイルサイズ */
+    size: number;
+    /** ファイルのMIMEタイプ */
+    type: string;
+    /** 画像の横幅。画像の場合のみ設定されます。 */
+    width?: number;
+    /** 画像の縦幅。画像の場合のみ設定されます。 */
+    height?: number;
+  };
+};
+```
+
+storage型カラムにファイルを紐づけるにはCMS SDKを使用します。  
+詳細は [storage型カラムにデータを保存](../cms-sdk/mutation-contents.md#storage型カラムにデータを保存) を参照してください。
+
+## 予約カラム
+
+以下のカラムは自動でテーブルに追加されます。
+
+### id
+
+レコードを一意に識別するためのIDです。
+
+ランダムな16文字の英数字で構成されます。（例: `MlKtexCT1v8CS4pR`）
+
+id には自動で [インデックス](#インデックス) が作成されます。
+
+### createdAt
+
+レコードが作成された日時です。
+
+ISO 8601 形式の文字列で構成されます。（例: `2025-01-01T00:00:00.000Z`）
+
+### updatedAt
+
+レコードが更新された日時です。
+
+ISO 8601 形式の文字列で構成されます。（例: `2025-01-01T00:00:00.000Z`）
+
+### group
+
+レコードの所属するグループです。[権限](./authority.md) の設定に使用します。
+
+任意の文字列を設定できます。デフォルトは `undefined` です。
+
+## インデックス
+
+インデックスはデータの検索速度を向上させるための仕組みです。
+
+> [!WARNING]
+> 絞り込みや並び替えの速度が向上する反面、データの追加や更新、削除の速度は低下します。リレーショナルデータベースにおけるインデックス設計の一般的なベストプラクティスに従って、データの操作パターンを考慮して注意深く設計してください。
+
+`id` カラムには自動でインデックスが作成されるため、追加の設定は不要です。
+
+スキーマでは以下のようにテーブル定義の中で `indexes` プロパティを利用して設定します。
+
+```ts copy filename="orizm.config.ts" showLineNumbers {14-21}
+import { defineConfig } from "@orizm/cli/config";
+
+export default defineConfig({
+  tables: {
+    employee: {
+      columns: {
+        name: {
+          type: "string",
+        },
+        department: {
+          type: "string",
+        },
+      },
+      indexes: [
+        {
+          columns: ["name"],
+        },
+        {
+          columns: ["department", "name"],
+        },
+      ],
+    },
+  },
+});
+```
+
+### unique
+
+`unique` プロパティを `true` にすることで、ユニーク制約を設定できます。
+
+```ts copy filename="orizm.config.ts" showLineNumbers {14}
+import { defineConfig } from "@orizm/cli/config";
+
+export default defineConfig({
+  tables: {
+    blog: {
+      columns: {
+        slug: {
+          type: "string",
+        },
+        title: {
+          type: "string",
+        },
+      },
+      indexes: [{ columns: ["slug"], unique: true }],
+    },
+  },
+});
+```
+
+## 高度な機能
+
+テーブルでは以下のような高度な機能を設定できます。
+
+- [下書き管理](../draft.md)
+- [全文検索](../full-text-search.md)
+- [編集履歴管理](../history.md)
+- [フォーム管理](../form/about.md)

package/dist/docs/features/schema/table-module.md

@@ -0,0 +1,140 @@
+<!-- source: docs/src/app/features/schema/table-module/page.mdx -->
+
+# テーブルモジュール
+
+テーブルモジュール（以下、モジュール）は、データベースで複雑なデータ構造を表現するための機能です。
+
+## 基本概念
+
+モジュールを利用すると、リレーショナルデータベースでは通常表現できない階層構造やリスト構造を表現できます。
+
+モジュールは以下のデータ型のカラムで使用できます。
+
+1. **module型**: カラムに対して1つのデータを関連付けます。(1:1)
+1. **module-array型**: カラムに対して複数のデータを関連付けます。(1:N)
+
+モジュールの特徴は以下の通りです。
+
+- 再帰的にネスト可能
+- テーブルと同様にreference型やインデックス、ユニーク制約を設定可能
+- 検索条件としてモジュールのカラムを指定可能
+
+## スキーマの定義
+
+まず、スキーマの `tableModules` プロパティでモジュールを定義します。モジュールはテーブルの定義と同様の構文で定義できます。定義方法については [データベース](./database.md) を参照してください。
+
+モジュールを定義したら、テーブルのカラム定義で `module` または `module-array` 型を指定してモジュールを関連付けます。
+
+> [!WARNING]
+> **注意**  
+> カラム名とモジュール名を同じにすることはできません。
+>
+
+以下は、画像ギャラリーを持つブログ記事を表現するスキーマの例です。
+
+```ts copy filename="orizm.config.ts" showLineNumbers
+import { defineConfig } from "@orizm/cli/config";
+
+// ① tableModules に imageWithCaption モジュールを定義
+// ② tables に blog テーブルを定義
+// ③ blog のカラム imageGallery に imageWithCaption モジュールを関連付け
+
+export default defineConfig({
+  tableModules: {
+    // ①
+    imageWithCaption: {
+      columns: {
+        image: {
+          type: "storage",
+        },
+        caption: {
+          type: "string",
+        },
+      },
+    },
+  },
+  tables: {
+    // ②
+    blog: {
+      columns: {
+        title: {
+          type: "string",
+          required: true,
+        },
+        body: {
+          type: "string",
+        },
+        // ③
+        imageGallery: {
+          type: "module-array",
+          moduleName: "imageWithCaption",
+        },
+      },
+    },
+  },
+});
+```
+
+## 予約カラム
+
+`module` と `module-array` 型には以下の予約カラムがあります。
+
+### id
+
+モジュールのデータを一意に識別するためのIDです。ランダムな16文字の英数字で構成されます。  
+（例: `MlKtexCT1v8CS4pR`）
+
+`id` には自動で [インデックス](#インデックス) が作成されます。
+
+### \_parentId
+
+親レコードのIDを持ちます。
+
+### \_order
+
+リストの並び順です。module-array型にのみ存在します。
+
+## フィルタ
+
+SDKから `list()` でクエリする際、`module-array` 型のカラムに対して `some`、`every`、`none` 演算子を使用して配列要素を条件にフィルタリングできます。詳細は [CMS SDKのフィルタ](../cms-sdk/fetch-contents.md#module-array-のフィルタ) または [Consumer SDKのフィルタ](../consumer-sdk/fetch-contents.md#module-array-のフィルタ) を参照してください。
+
+## 注意事項
+
+- カラム名とモジュール名を同じにすることはできません。
+- SDKから `list()` でクエリする際、`order` パラメータでモジュールのカラムを指定できません。
+- `module` と `module-array` 型は `required` の指定ができません。
+- モジュールのデータには直接アクセスできません。必ずレコードを通してアクセスする必要があります。
+
+## reference型との違い
+
+reference型は他のテーブルのレコードを参照する際に使用します。module型に近い性質を持ちますが、以下のような目的の違いがあります。
+
+- **reference**: 異なるテーブルのレコードとの関連付け
+- **module**: 1レコード内での階層構造やリスト構造の実現
+
+モジュールにはテーブルとしての実体は無く、レコードの内部にデータを持ちます。reference型では参照先のレコードは独立して存在できますが、モジュールは親レコードが存在しないと自身も存在できません。
+
+![referenceとmoduleの違い](./reference-vs-module.png)
+
+以下のように使い分けることができます。
+
+**reference型が適するケース**
+
+- 一般的なリレーショナルデータベースのリレーションで表現したいケース
+- 複数のテーブルから参照するケース
+
+**module型が適するケース**
+
+- NoSQLライクなドキュメント構造を型安全に表現したいケース
+- 親レコードに従属するデータを表現したいケース
+
+## json型との違い
+
+json型を使うことで、モジュールのような階層構造やリスト構造を持つデータを扱うことができます。
+
+異なる点として、json型は生成されるTypeScript型定義が `unknown` になるため、アプリケーション側で型定義やバリデーションを行う必要があります。モジュールはスキーマ定義に基づいて型定義が生成されるため、型安全にデータを扱うことができます。
+
+以下のように使い分けることができます。
+
+- **複雑な型を手軽に扱いたい**: `json`
+- **型安全にデータを扱いたい**: `module`, `module-array`