@proteinjs/db 1.19.0 → 1.20.1

package/test/util/DbTestEnvironment.ts

@@ -0,0 +1,46 @@
+import { Table, DbDriver } from '@proteinjs/db';
+import { cascadeDeleteTestTables } from './tables/cascadeDeleteTestTables';
+import { columnTypesTestTables } from './tables/columnTypesTestTables';
+import { crudTestTables } from './tables/crudTestTables';
+import { dynamicReferenceTestTables } from './tables/dynamicReferenceColumnTestTables';
+import { tableManagerTestTables } from './tables/tableManagerTestTables';
+import { transactionTestTables } from './tables/transactionTestTables';
+
+const TABLES: Table<any>[] = [
+  ...Object.values(cascadeDeleteTestTables),
+  ...Object.values(columnTypesTestTables),
+  ...Object.values(crudTestTables),
+  ...Object.values(dynamicReferenceTestTables),
+  ...Object.values(tableManagerTestTables),
+  ...Object.values(transactionTestTables),
+];
+
+/**
+ * Convenience functions for setting up a test environment
+ */
+export class DbTestEnvironment {
+  constructor(
+    private dbDriver: DbDriver,
+    private dropTestTable: (table: Table<any>) => Promise<void>
+  ) {}
+
+  async beforeAll() {
+    if (this.dbDriver.start) {
+      await this.dbDriver.start();
+    }
+
+    for (const table of TABLES) {
+      await this.dbDriver.getTableManager().loadTable(table);
+    }
+  }
+
+  async afterAll() {
+    for (const table of TABLES.reverse()) {
+      await this.dropTestTable(table);
+    }
+
+    if (this.dbDriver.stop) {
+      await this.dbDriver.stop();
+    }
+  }
+}

package/test/util/tables/cascadeDeleteTestTables.ts

@@ -0,0 +1,232 @@
+import {
+  StringColumn,
+  ReferenceColumn,
+  ReferenceArrayColumn,
+  DynamicReferenceColumn,
+  DynamicReferenceTableNameColumn,
+  Table,
+  withRecordColumns,
+  Record,
+  Reference,
+  ReferenceArray,
+} from '@proteinjs/db';
+
+// --- Cascade: ReferenceColumn (GroupRef -> MemberRef)
+export interface MemberRef extends Record {
+  name: string;
+}
+export interface GroupRef extends Record {
+  groupName: string;
+  memberRef?: Reference<MemberRef> | null;
+}
+
+// --- Cascade: ReferenceArrayColumn (GroupArr -> MemberArr[])
+export interface MemberArr extends Record {
+  name: string;
+}
+export interface GroupArr extends Record {
+  groupName: string;
+  memberRefs?: ReferenceArray<MemberArr> | null;
+}
+
+// --- Cascade: DynamicReferenceColumn (GroupDyn -> MemberDyn)
+export interface MemberDyn extends Record {
+  name: string;
+}
+export interface GroupDyn extends Record {
+  groupName: string;
+  memberDynTableName?: string | null;
+  memberDynRef?: Reference<MemberDyn> | null;
+}
+
+// --- Reverse: ReferenceColumn (Comment -> Post)
+export interface Post extends Record {
+  title: string;
+}
+export interface Comment extends Record {
+  text: string;
+  postRef?: Reference<Post> | null;
+}
+
+// --- Reverse: ReferenceArrayColumn (GroupArrRev -> MemberArrRev[])
+export interface MemberArrRev extends Record {
+  name: string;
+}
+export interface GroupArrRev extends Record {
+  groupName: string;
+  memberRefs?: ReferenceArray<MemberArrRev> | null;
+}
+
+// --- Reverse: DynamicReferenceColumn (Task -> Worker)
+export interface Worker extends Record {
+  name: string;
+}
+export interface Task extends Record {
+  title: string;
+  assigneeTableName?: string | null;
+  assigneeRef?: Reference<Worker> | null;
+}
+
+/**
+ * ---------- Table Names ----------
+ */
+// Cascade (ReferenceColumn)
+const MEMBER_REF_TABLE = 'db_test_cd_members_ref';
+const GROUP_REF_TABLE = 'db_test_cd_groups_ref';
+
+// Cascade (ReferenceArrayColumn)
+const MEMBER_ARR_TABLE = 'db_test_cd_members_arr';
+const GROUP_ARR_TABLE = 'db_test_cd_groups_arr';
+
+// Cascade (DynamicReferenceColumn)
+const MEMBER_DYN_TABLE = 'db_test_cd_members_dyn';
+const GROUP_DYN_TABLE = 'db_test_cd_groups_dyn';
+
+// Reverse (ReferenceColumn)
+const POST_TABLE = 'db_test_cd_posts';
+const COMMENT_TABLE = 'db_test_cd_comments';
+
+// Reverse (ReferenceArrayColumn)
+const MEMBER_ARR_REV_TABLE = 'db_test_cd_members_arr_rev';
+const GROUP_ARR_REV_TABLE = 'db_test_cd_groups_arr_rev';
+
+// Reverse (DynamicReferenceColumn)
+const WORKER_TABLE = 'db_test_cd_workers';
+const TASK_TABLE = 'db_test_cd_tasks';
+
+/**
+ * ---------- Table Classes ----------
+ */
+// Cascade: ReferenceColumn
+export class MemberRefTable extends Table<MemberRef> {
+  name = MEMBER_REF_TABLE;
+  columns = withRecordColumns<MemberRef>({
+    name: new StringColumn('name'),
+  });
+}
+export class GroupRefTable extends Table<GroupRef> {
+  name = GROUP_REF_TABLE;
+  columns = withRecordColumns<GroupRef>({
+    groupName: new StringColumn('group_name'),
+    memberRef: new ReferenceColumn<MemberRef>(
+      'member_id',
+      MEMBER_REF_TABLE,
+      true // cascade: deleting GroupRef deletes the referenced MemberRef
+    ),
+  });
+}
+
+// Cascade: ReferenceArrayColumn
+export class MemberArrTable extends Table<MemberArr> {
+  name = MEMBER_ARR_TABLE;
+  columns = withRecordColumns<MemberArr>({
+    name: new StringColumn('name'),
+  });
+}
+export class GroupArrTable extends Table<GroupArr> {
+  name = GROUP_ARR_TABLE;
+  columns = withRecordColumns<GroupArr>({
+    groupName: new StringColumn('group_name'),
+    memberRefs: new ReferenceArrayColumn<MemberArr>(
+      'member_ids',
+      MEMBER_ARR_TABLE,
+      true // cascade: deleting GroupArr deletes all referenced MemberArr
+    ),
+  });
+}
+
+// Cascade: DynamicReferenceColumn
+export class MemberDynTable extends Table<MemberDyn> {
+  name = MEMBER_DYN_TABLE;
+  columns = withRecordColumns<MemberDyn>({
+    name: new StringColumn('name'),
+  });
+}
+export class GroupDynTable extends Table<GroupDyn> {
+  name = GROUP_DYN_TABLE;
+  columns = withRecordColumns<GroupDyn>({
+    groupName: new StringColumn('group_name'),
+    memberDynTableName: new DynamicReferenceTableNameColumn('member_dyn_table_name', 'member_dyn_ref'),
+    memberDynRef: new DynamicReferenceColumn<MemberDyn>(
+      'member_dyn_ref',
+      'member_dyn_table_name',
+      true // cascade: deleting GroupDyn deletes dynamically referenced MemberDyn
+    ),
+  });
+}
+
+// Reverse: ReferenceColumn
+export class PostTable extends Table<Post> {
+  name = POST_TABLE;
+  columns = withRecordColumns<Post>({
+    title: new StringColumn('title'),
+  });
+}
+export class CommentTable extends Table<Comment> {
+  name = COMMENT_TABLE;
+  columns = withRecordColumns<Comment>({
+    text: new StringColumn('text'),
+    postRef: new ReferenceColumn<Post>(
+      'post_id',
+      POST_TABLE,
+      false,
+      { reverseCascadeDelete: true } // reverse: deleting Post deletes Comment
+    ),
+  });
+}
+
+// Reverse: ReferenceArrayColumn
+export class MemberArrRevTable extends Table<MemberArrRev> {
+  name = MEMBER_ARR_REV_TABLE;
+  columns = withRecordColumns<MemberArrRev>({
+    name: new StringColumn('name'),
+  });
+}
+export class GroupArrRevTable extends Table<GroupArrRev> {
+  name = GROUP_ARR_REV_TABLE;
+  columns = withRecordColumns<GroupArrRev>({
+    groupName: new StringColumn('group_name'),
+    memberRefs: new ReferenceArrayColumn<MemberArrRev>(
+      'member_ids',
+      MEMBER_ARR_REV_TABLE,
+      false,
+      { reverseCascadeDelete: true } // reverse: deleting any MemberArrRev deletes the GroupArrRev
+    ),
+  });
+}
+
+// Reverse: DynamicReferenceColumn
+export class WorkerTable extends Table<Worker> {
+  name = WORKER_TABLE;
+  columns = withRecordColumns<Worker>({
+    name: new StringColumn('name'),
+  });
+}
+export class TaskTable extends Table<Task> {
+  name = TASK_TABLE;
+  columns = withRecordColumns<Task>({
+    title: new StringColumn('title'),
+    assigneeTableName: new DynamicReferenceTableNameColumn('assignee_table_name', 'assignee_ref'),
+    assigneeRef: new DynamicReferenceColumn<Worker>(
+      'assignee_ref',
+      'assignee_table_name',
+      false,
+      { reverseCascadeDelete: true } // reverse: deleting Worker deletes Task
+    ),
+  });
+}
+
+export const cascadeDeleteTestTables = {
+  MemberRef: new MemberRefTable() as Table<MemberRef>,
+  GroupRef: new GroupRefTable() as Table<GroupRef>,
+  MemberArr: new MemberArrTable() as Table<MemberArr>,
+  GroupArr: new GroupArrTable() as Table<GroupArr>,
+  MemberDyn: new MemberDynTable() as Table<MemberDyn>,
+  GroupDyn: new GroupDynTable() as Table<GroupDyn>,
+  Post: new PostTable() as Table<Post>,
+  Comment: new CommentTable() as Table<Comment>,
+  MemberArrRev: new MemberArrRevTable() as Table<MemberArrRev>,
+  GroupArrRev: new GroupArrRevTable() as Table<GroupArrRev>,
+  Worker: new WorkerTable() as Table<Worker>,
+  Task: new TaskTable() as Table<Task>,
+};

package/test/util/tables/columnTypesTestTables.ts

@@ -0,0 +1,63 @@
+import { Moment } from 'moment';
+import {
+  ReferenceArray,
+  Reference,
+  withRecordColumns,
+  Record,
+  Table,
+  IntegerColumn,
+  StringColumn,
+  FloatColumn,
+  DecimalColumn,
+  BooleanColumn,
+  DateColumn,
+  DateTimeColumn,
+  BinaryColumn,
+  UuidColumn,
+  PasswordColumn,
+  ObjectColumn,
+  ArrayColumn,
+  ReferenceArrayColumn,
+  ReferenceColumn,
+} from '@proteinjs/db';
+
+export interface TestRecord extends Record {
+  integerColumn?: number | null;
+  stringColumn?: string | null;
+  floatColumn?: number | null;
+  decimalColumn?: number | null;
+  booleanColumn?: boolean | null;
+  dateColumn?: Date | null;
+  dateTimeColumn?: Moment | null;
+  binaryColumn?: number | null;
+  uuidColumn?: string | null;
+  passwordColumn?: string | null;
+  objectColumn?: any | null;
+  arrayColumn?: any[] | null;
+  referenceArrayColumn?: ReferenceArray<any> | null;
+  referenceColumn?: Reference<any> | null;
+}
+
+export class TestTable extends Table<TestRecord> {
+  public name = 'db_test_ct_table';
+  public columns = withRecordColumns<TestRecord>({
+    integerColumn: new IntegerColumn('integer_column'),
+    stringColumn: new StringColumn('string_column', {}, 255),
+    floatColumn: new FloatColumn('float_column'),
+    decimalColumn: new DecimalColumn('decimal_column'),
+    booleanColumn: new BooleanColumn('boolean_column'),
+    dateColumn: new DateColumn('date_column'),
+    dateTimeColumn: new DateTimeColumn('date_time_column'),
+    binaryColumn: new BinaryColumn('binary_column'),
+    uuidColumn: new UuidColumn('uuid_column'),
+    passwordColumn: new PasswordColumn('password_column'),
+    objectColumn: new ObjectColumn('object_column'),
+    arrayColumn: new ArrayColumn('array_column'),
+    referenceArrayColumn: new ReferenceArrayColumn('reference_array_column', 'reference_table', false),
+    referenceColumn: new ReferenceColumn('reference_column', 'reference_table', false),
+  });
+}
+
+export const columnTypesTestTables = {
+  Test: new TestTable() as Table<TestRecord>,
+};

package/test/util/tables/crudTestTables.ts

@@ -0,0 +1,44 @@
+import { withRecordColumns, Record, BooleanColumn, DateColumn, StringColumn, Table } from '@proteinjs/db';
+
+export interface Employee extends Record {
+  name: string;
+  department?: string;
+  jobTitle?: string | null;
+  isRemote?: boolean;
+  startDate?: Date;
+  object?: string;
+}
+
+export class EmployeeTestTable extends Table<Employee> {
+  name = 'db_test_employee';
+  columns = withRecordColumns<Employee>({
+    name: new StringColumn('name'),
+    department: new StringColumn('department'),
+    isRemote: new BooleanColumn('is_remote'),
+    jobTitle: new StringColumn('job_title'),
+    startDate: new DateColumn('start_date'),
+    object: new StringColumn('object'),
+  });
+}
+
+export interface ReservedWordTest extends Record {
+  name: string;
+  order?: string;
+  select?: string;
+  join?: string;
+}
+
+export class ReservedWordTestTable extends Table<ReservedWordTest> {
+  name = 'db_test_reserved_word';
+  columns = withRecordColumns<ReservedWordTest>({
+    name: new StringColumn('name'),
+    order: new StringColumn('order'),
+    select: new StringColumn('select'),
+    join: new StringColumn('join'),
+  });
+}
+
+export const crudTestTables = {
+  Employee: new EmployeeTestTable() as Table<Employee>,
+  ReservedWordTest: new ReservedWordTestTable() as Table<ReservedWordTest>,
+};

package/test/util/tables/dynamicReferenceColumnTestTables.ts

@@ -0,0 +1,87 @@
+import {
+  DynamicReferenceColumn,
+  StringColumn,
+  DynamicReferenceTableNameColumn,
+  Reference,
+  Table,
+  withRecordColumns,
+  Record,
+} from '@proteinjs/db';
+
+export interface ProjectAssignment extends Record {
+  projectName: string;
+  employeeTableName?: string | null;
+  employeeRef?: Reference<Engineer | Designer | ProjectManager> | null;
+  projectLeadTableName?: string | null;
+  projectLeadRef?: Reference<Engineer | Designer | ProjectManager> | null;
+  startDate: string;
+}
+
+export interface Engineer extends Record {
+  name: string;
+  yearsOfExperience: number;
+}
+
+export interface Designer extends Record {
+  name: string;
+  specialization: string;
+}
+
+export interface ProjectManager extends Record {
+  name: string;
+  certificate: string;
+}
+
+export class ProjectAssignmentTable extends Table<ProjectAssignment> {
+  name = 'db_test_dr_project_assignments';
+  columns = withRecordColumns<ProjectAssignment>({
+    projectName: new StringColumn('project_name'),
+    employeeTableName: new DynamicReferenceTableNameColumn('employee_table_name', 'employee_ref'),
+    employeeRef: new DynamicReferenceColumn<Engineer | Designer | ProjectManager>(
+      'employee_ref',
+      'employee_table_name',
+      true // Enable cascade delete for testing
+    ),
+    projectLeadTableName: new DynamicReferenceTableNameColumn('project_lead_table_name', 'project_lead_ref', {
+      defaultValue: async () => 'TEST_DEFAULT_VALUE',
+      updateValue: async () => 'TEST_UPDATE_VALUE',
+    }),
+    projectLeadRef: new DynamicReferenceColumn<Engineer | Designer | ProjectManager>(
+      'project_lead_ref',
+      'project_lead_table_name',
+      true // Enable cascade delete for testing
+    ),
+    startDate: new StringColumn('start_date'),
+  });
+}
+
+export class EngineerTable extends Table<Engineer> {
+  name = 'db_test_dr_engineers';
+  columns = withRecordColumns<Engineer>({
+    name: new StringColumn('name'),
+    yearsOfExperience: new StringColumn('years_of_experience'),
+  });
+}
+
+export class DesignerTable extends Table<Designer> {
+  name = 'db_test_dr_designers';
+  columns = withRecordColumns<Designer>({
+    name: new StringColumn('name'),
+    specialization: new StringColumn('specialization'),
+  });
+}
+
+export class ProjectManagerTable extends Table<ProjectManager> {
+  name = 'db_test_dr_project_managers';
+  columns = withRecordColumns<ProjectManager>({
+    name: new StringColumn('name'),
+    certificate: new StringColumn('certificate'),
+  });
+}
+
+export const dynamicReferenceTestTables = {
+  ProjectAssignment: new ProjectAssignmentTable() as Table<ProjectAssignment>,
+  Engineer: new EngineerTable() as Table<Engineer>,
+  Designer: new DesignerTable() as Table<Designer>,
+  ProjectManager: new ProjectManagerTable() as Table<ProjectManager>,
+};

package/test/util/tables/tableManagerTestTables.ts

@@ -0,0 +1,98 @@
+import {
+  BinaryColumn,
+  BooleanColumn,
+  DateColumn,
+  DateTimeColumn,
+  DecimalColumn,
+  FloatColumn,
+  IntegerColumn,
+  ObjectColumn,
+  StringColumn,
+  UuidColumn,
+  Record,
+  withRecordColumns,
+  Table,
+} from '@proteinjs/db';
+
+export interface User extends Record {
+  name: string;
+  email: string;
+  active: boolean;
+}
+
+export class UserTestTable extends Table<User> {
+  name = 'db_test_user';
+  columns = withRecordColumns<User>({
+    name: new StringColumn('name'),
+    email: new StringColumn('email'),
+    active: new BooleanColumn('active'),
+  });
+  indexes = [
+    { name: 'db_test_user_email_index', columns: ['email'] as (keyof User)[] },
+    { name: 'db_test_user_active_email_index', columns: ['active', 'email'] as (keyof User)[] },
+  ];
+}
+
+export interface MappedIndexUser extends Record {
+  emailAddress: string;
+  accountStatus: string;
+  createdOn: Date;
+}
+
+export class MappedIndexUserTable extends Table<MappedIndexUser> {
+  name = 'db_test_tm_mapped_index_user';
+  columns = withRecordColumns<MappedIndexUser>({
+    emailAddress: new StringColumn('email_address'),
+    accountStatus: new StringColumn('account_status'),
+    createdOn: new DateColumn('created_on'),
+  });
+  indexes = [
+    {
+      name: 'db_test_mapped_index_user_email_index',
+      columns: ['emailAddress'] as (keyof MappedIndexUser)[],
+    },
+    {
+      name: 'db_test_mapped_index_user_status_email_index',
+      columns: ['accountStatus', 'emailAddress'] as (keyof MappedIndexUser)[],
+    },
+  ];
+}
+
+export interface ColumnTypes extends Record {
+  integer: number;
+  bigInteger: number;
+  text: string;
+  string: string;
+  float: number;
+  decimal: number;
+  boolean: boolean;
+  date: Date;
+  dateTime: moment.Moment;
+  binary: boolean;
+  object: any;
+  uuid: string;
+}
+
+export class ColumnTypesTable extends Table<ColumnTypes> {
+  name = 'db_test_tm_column_types';
+  columns = withRecordColumns<ColumnTypes>({
+    integer: new IntegerColumn('integer', { nullable: true }),
+    bigInteger: new IntegerColumn('big_integer', { nullable: false }, true),
+    string: new StringColumn('string', { references: { table: 'db_test_user' } }),
+    text: new StringColumn('text', undefined, 'MAX'),
+    float: new FloatColumn('float', { defaultValue: async () => 0.5 }),
+    decimal: new DecimalColumn('decimal'),
+    boolean: new BooleanColumn('boolean'),
+    date: new DateColumn('date'),
+    dateTime: new DateTimeColumn('date_time'),
+    binary: new BinaryColumn('binary'),
+    object: new ObjectColumn('object'),
+    uuid: new UuidColumn('uuid', { unique: { unique: true } }),
+  });
+}
+
+export const tableManagerTestTables = {
+  User: new UserTestTable() as Table<User>,
+  MappedIndexUser: new MappedIndexUserTable() as Table<MappedIndexUser>,
+  ColumnTypes: new ColumnTypesTable() as Table<ColumnTypes>,
+};

package/test/util/tables/transactionTestTables.ts

@@ -0,0 +1,44 @@
+import { withRecordColumns, Record, BooleanColumn, DateColumn, StringColumn, Table } from '@proteinjs/db';
+
+export interface TransactionEmployee extends Record {
+  name: string;
+  department?: string;
+  jobTitle?: string | null;
+  isRemote?: boolean;
+  startDate?: Date;
+  object?: string;
+}
+
+export class TransactionEmployeeTestTable extends Table<TransactionEmployee> {
+  name = 'db_test_transaction_employee';
+  columns = withRecordColumns<TransactionEmployee>({
+    name: new StringColumn('name'),
+    department: new StringColumn('department'),
+    isRemote: new BooleanColumn('is_remote'),
+    jobTitle: new StringColumn('job_title'),
+    startDate: new DateColumn('start_date'),
+    object: new StringColumn('object'),
+  });
+}
+
+export interface TransactionReservedWordTest extends Record {
+  name: string;
+  order?: string;
+  select?: string;
+  join?: string;
+}
+
+export class TransactionReservedWordTestTable extends Table<TransactionReservedWordTest> {
+  name = 'db_test_transaction_reserved_word';
+  columns = withRecordColumns<TransactionReservedWordTest>({
+    name: new StringColumn('name'),
+    order: new StringColumn('order'),
+    select: new StringColumn('select'),
+    join: new StringColumn('join'),
+  });
+}
+
+export const transactionTestTables = {
+  TransactionEmployee: new TransactionEmployeeTestTable() as Table<TransactionEmployee>,
+  TransactionReservedWord: new TransactionReservedWordTestTable() as Table<TransactionReservedWordTest>,
+};

package/tsconfig.json

@@ -14,6 +14,12 @@
     "forceConsistentCasingInFileNames": true,
     "resolveJsonModule": true,
     "typeRoots": ["./node_modules/@types"],
-    "types": ["node", "jest"]
+    "types": ["node", "jest"],
+    "baseUrl": ".",
+    "paths": {
+      "@proteinjs/db": ["index.ts"],
+      "@proteinjs/db/*": ["src/*"],
+      "@proteinjs/db/test": ["test/index.ts"]
+    }
   }
 }

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2023 Brent Bahry
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.