From e0e8dcb6b451247f5cf69d9339f8de69700b196d Mon Sep 17 00:00:00 2001
From: DominicGBauer <dominic@nomanini.com>
Date: Wed, 28 Aug 2024 17:41:39 +0200
Subject: [PATCH] chore: add comments

---
 packages/common/src/db/schema/Schema.ts  | 10 ++++-
 packages/common/src/db/schema/Table.ts   | 53 +++++++++++++++++++++++-
 packages/common/src/db/schema/TableV2.ts |  4 +-
 3 files changed, 64 insertions(+), 3 deletions(-)

diff --git a/packages/common/src/db/schema/Schema.ts b/packages/common/src/db/schema/Schema.ts
index e97b92fd..6ab4ce54 100644
--- a/packages/common/src/db/schema/Schema.ts
+++ b/packages/common/src/db/schema/Schema.ts
@@ -34,13 +34,21 @@ export class Schema<S extends SchemaType = SchemaType> {
 
   toJSON() {
     return {
+      // This is required because "name" field is not present in TableV2
       tables: this.tables.map((t) => t.toJSON())
     };
   }
 
   private convertToClassicTables(props: S) {
     return Object.entries(props).map(([name, table]) => {
-      const convertedTable = new Table({ name, columns: table.columns });
+      const convertedTable = new Table({
+        name,
+        columns: table.columns,
+        indexes: table.indexes,
+        localOnly: table.localOnly,
+        insertOnly: table.insertOnly,
+        viewName: table.viewName
+      });
       return convertedTable;
     });
   }
diff --git a/packages/common/src/db/schema/Table.ts b/packages/common/src/db/schema/Table.ts
index 31fae330..1ecea293 100644
--- a/packages/common/src/db/schema/Table.ts
+++ b/packages/common/src/db/schema/Table.ts
@@ -68,7 +68,7 @@ export class Table<Columns extends ColumnsType = ColumnsType> {
   static createTable(name: string, table: Table) {
     return new Table({
       name,
-      columns: Object.entries(table.columns).map(([name, col]) => new Column({ name, type: col.type })),
+      columns: table.columns,
       indexes: table.indexes,
       localOnly: table.options.localOnly,
       insertOnly: table.options.insertOnly,
@@ -76,7 +76,58 @@ export class Table<Columns extends ColumnsType = ColumnsType> {
     });
   }
 
+  /**
+   * Creates a new Table instance.
+   *
+   * This constructor supports two different versions:
+   * 1. New constructor: Using a Columns object and an optional TableV2Options object
+   * 2. Deprecated constructor: Using a TableOptions object (will be removed in the next major release)
+   *
+   * @constructor
+   * @param {Columns | TableOptions} optionsOrColumns - Either a Columns object (for V2 syntax) or a TableOptions object (for V1 syntax)
+   * @param {TableV2Options} [v2Options] - Optional configuration options for V2 syntax
+   *
+   * @example
+   * <caption>New constructor example</caption>
+   * ```javascript
+   * const table = new Table(
+   *   {
+   *     name: { type: ColumnType.TEXT },
+   *     age: { type: ColumnType.INTEGER }
+   *   },
+   *   { indexes: { nameIndex: ['name'] } }
+   * );
+   *```
+   *
+   *
+   * @example
+   * <caption>Deprecated constructor example</caption>
+   * ```javascript
+   * const table = new Table({
+   *   name: 'users',
+   *   columns: [
+   *     new Column({ name: 'name', type: ColumnType.TEXT }),
+   *     new Column({ name: 'age', type: ColumnType.INTEGER })
+   *   ]
+   * });
+   *```
+   */
   constructor(columns: Columns, options?: TableV2Options);
+  /**
+  * @deprecated This constructor will be removed in the next major release.
+  * Use the new constructor shown below instead.
+  * @example
+  * <caption>Use this instead</caption>
+  * ```javascript
+  *   const table = new Table(
+  *     {
+  *       name: { type: ColumnType.TEXT },
+  *       age: { type: ColumnType.INTEGER }
+  *     },
+  *     { indexes: { nameIndex: ['name'] } }
+  *   );
+  *```
+  */
   constructor(options: TableOptions);
   constructor(optionsOrColumns: Columns | TableOptions, v2Options?: TableV2Options) {
     if (this.isTableV1(optionsOrColumns)) {
diff --git a/packages/common/src/db/schema/TableV2.ts b/packages/common/src/db/schema/TableV2.ts
index c65fa5e2..47e81c0f 100644
--- a/packages/common/src/db/schema/TableV2.ts
+++ b/packages/common/src/db/schema/TableV2.ts
@@ -1,7 +1,9 @@
 import { ColumnsType } from './Column';
 import { Table } from './Table';
 
-/*
+/**
   Generate a new table from the columns and indexes
+  @deprecated You should use {@link Table} instead as it now allows TableV2 syntax.
+  This will be removed in the next major release.
 */
 export class TableV2<Columns extends ColumnsType = ColumnsType> extends Table<Columns> {}