tantan-typeorm-gs 1.0.0

package/docs/development.md

@@ -0,0 +1,243 @@
+## Development Guide
+
+This guide describes the development workflow for contributing to `tantan-typeorm-gs`.
+
+### Requirements
+
+The project uses:
+
+- Bun
+- TypeScript
+- TypeORM
+- Google Sheets API
+
+Install the project dependencies:
+
+```bash id="7m2x4p"
+bun install
+```
+
+### Project Structure
+
+The project is organized around several main layers:
+
+```text id="5q8n1v"
+src/
+├── client/
+│   └── index.ts
+│
+└── core/
+    ├── driver.ts
+    ├── memory.ts
+    ├── data-source.ts
+    ├── schema-builder.ts
+    ├── types.ts
+    ├── utils.ts
+    └── query/
+       ├── interpreter.ts
+       ├── runner.ts
+       └── types.ts
+
+
+```
+
+The main execution flow is:
+
+```text id="3v7k9c"
+TypeORM Repository
+        ↓
+QueryBuilder
+        ↓
+GoogleSheetsQueryRunner
+        ↓
+GoogleSheetsQueryInterpreter
+        ↓
+GoogleSheetsClient
+        ↓
+Google Sheets API
+```
+
+### Development Principles
+
+Changes should be made at the layer responsible for the behavior.
+
+For example:
+
+| Concern                  | Main layer                     |
+| ------------------------ | ------------------------------ |
+| Google API communication | `GoogleSheetsApiClient`        |
+| Driver behavior          | `GoogleSheetsDriver`           |
+| SQL/query interpretation | `GoogleSheetsQueryInterpreter` |
+| Query execution          | `GoogleSheetsQueryRunner`      |
+| Data source registration | `GoogleSheetsDataSource`       |
+| Driver errors            | `error.ts`                     |
+
+Avoid implementing the same behavior in multiple layers.
+
+### Running Tests
+
+Run the complete test suite:
+
+```bash id="8c4m2x"
+bun test
+```
+
+Run TypeScript type checking:
+
+```bash id="1v7n5q"
+bun run typecheck
+```
+
+Individual test files can also be executed directly:
+
+```bash id="6m3k9p"
+bun test test/google-sheets/0001-client.test.ts
+```
+
+Performance tests are kept separate:
+
+```bash id="4q8x1c"
+bun test test/google-sheets/0007-performance.test.ts
+```
+
+### Test Strategy
+
+The project separates driver tests from Google API integration tests.
+
+Driver and repository behavior should generally use `Memory`.
+
+```ts id="9p2v6m"
+const client = new Memory({
+	users: []
+});
+```
+
+This keeps tests fast and deterministic.
+
+The real `GoogleSheetsApiClient` is used for API integration tests.
+
+### Adding a New Feature
+
+When implementing a new feature:
+
+1. Identify the responsible layer.
+2. Add or update the relevant test.
+3. Implement the smallest required production change.
+4. Run the focused test.
+5. Run type checking.
+6. Run the complete test suite.
+7. Update the documentation when the supported behavior changes.
+
+A typical workflow is:
+
+```bash id="2x6m8q"
+bun test <focused-test>
+bun run typecheck
+bun test
+```
+
+### Avoid Unnecessary Changes
+
+The driver has multiple compatibility layers with TypeORM.
+
+A seemingly small change can affect existing repository behavior.
+
+When a test already covers stable behavior, avoid changing its implementation unless a concrete regression or missing requirement has been identified.
+
+Prefer targeted changes over broad refactoring.
+
+### Adding Tests
+
+Tests should verify behavior rather than implementation details whenever possible.
+
+For example, repository behavior should preferably be tested through:
+
+```ts id="5n9q3v"
+const repository = dataSource.getRepository(User);
+
+const users = await repository.find();
+```
+
+Direct `QueryRunner` tests are appropriate when behavior cannot be reliably exercised through the repository API.
+
+This is particularly useful for low-level driver validation such as explicit primary-key handling.
+
+### Performance Tests
+
+Performance tests should remain separate from functional tests.
+
+The existing performance baseline uses `Memory` and measures operations over 1,000 rows.
+
+Performance measurements should be treated as regression indicators rather than absolute guarantees.
+
+### Integration Tests
+
+Changes to the Google Sheets API client should also be validated against the real Google Sheets API where appropriate.
+
+Use a dedicated test spreadsheet and test credentials.
+
+Never use production spreadsheet data for automated integration tests.
+
+### TypeScript
+
+The project is written in TypeScript and should remain type-safe.
+
+Before submitting changes, run:
+
+```bash id="7c4m1x"
+bun run typecheck
+```
+
+Avoid using `any` unless the TypeORM or Google API boundary genuinely requires it.
+
+### Debugging
+
+When debugging driver behavior, trace the execution path from the repository toward the client:
+
+```text id="0v8n2q"
+Repository
+   ↓
+QueryBuilder
+   ↓
+QueryRunner
+   ↓
+Interpreter
+   ↓
+Client
+```
+
+This helps determine whether a problem originates from:
+
+- TypeORM query generation
+- query interpretation
+- driver execution
+- Google Sheets client behavior
+- Google Sheets API behavior
+
+### Pull Request Checklist
+
+Before submitting a change:
+
+```text id="3k7m1x"
+[ ] Focused tests pass
+[ ] TypeScript typecheck passes
+[ ] Full test suite passes
+[ ] Integration tests updated if necessary
+[ ] Performance tests considered if relevant
+[ ] Documentation updated if behavior changed
+[ ] No credentials or sensitive data committed
+[ ] No unrelated refactoring included
+```
+
+### Summary
+
+The development process should prioritize:
+
+- small, targeted changes
+- behavior-driven tests
+- clear separation between driver and API tests
+- TypeScript type safety
+- preserving existing compatibility
+- documentation that reflects tested capabilities
+
+The complete test suite should remain green before a change is considered complete.

package/docs/entities.md

@@ -0,0 +1,502 @@
+# Entity Definition
+
+`tantan-typeorm-gs` uses TypeORM entities to define the structure of data stored in Google Sheets.
+
+Each entity represents a worksheet, and each entity property represents a column in that worksheet.
+
+## Basic Entity
+
+A simple entity can be defined using TypeORM decorators:
+
+```ts
+import { Entity, PrimaryGeneratedColumn, Column } from "typeorm";
+
+@Entity("Users")
+export class User {
+	@PrimaryGeneratedColumn()
+	id!: number;
+
+	@Column()
+	name!: string;
+
+	@Column()
+	age!: number;
+
+	@Column()
+	active!: boolean;
+}
+```
+
+The entity above is mapped to a worksheet named `Users`.
+
+The corresponding worksheet structure is:
+
+| id  | name | age | active |
+| --- | ---- | --- | ------ |
+| 1   | Budi | 30  | TRUE   |
+| 2   | Siti | 25  | FALSE  |
+
+The worksheet name comes from the value passed to `@Entity()`.
+
+---
+
+## Entity Name
+
+Use `@Entity()` to define the worksheet name:
+
+```ts
+@Entity("Users")
+export class User {
+	// ...
+}
+```
+
+The name passed to `@Entity()` is used as the worksheet name.
+
+If the worksheet does not exist and synchronization is enabled, the driver can create it automatically.
+
+See [Synchronization](synchronization.md) for more information.
+
+---
+
+## Columns
+
+Use `@Column()` to define entity properties that are stored as worksheet columns:
+
+```ts
+@Entity("Users")
+export class User {
+	@PrimaryGeneratedColumn()
+	id!: number;
+
+	@Column()
+	name!: string;
+
+	@Column()
+	age!: number;
+
+	@Column()
+	active!: boolean;
+}
+```
+
+The property names are mapped to worksheet columns by TypeORM metadata.
+
+The driver supports the following commonly used types:
+
+| Type      | Status    |
+| --------- | --------- |
+| `string`  | Supported |
+| `number`  | Supported |
+| `boolean` | Supported |
+| `Date`    | Supported |
+| `uuid`    | Supported |
+| `int`     | Supported |
+
+Google Sheets commonly returns cell values as strings. The driver uses TypeORM column metadata to hydrate values into their expected application types.
+
+For example, a sheet value such as:
+
+```text
+30
+```
+
+can be hydrated as:
+
+```ts
+30; // number
+```
+
+when the entity property is declared as a numeric column.
+
+---
+
+## Primary Columns
+
+Entities should define a primary column.
+
+### Generated Primary Key
+
+Use `@PrimaryGeneratedColumn()` for automatically generated numeric IDs:
+
+```ts
+@Entity("Users")
+export class User {
+	@PrimaryGeneratedColumn()
+	id!: number;
+
+	@Column()
+	name!: string;
+}
+```
+
+The driver supports generated numeric IDs and UUIDs.
+
+### UUID Primary Key
+
+A UUID can be used as a generated primary key:
+
+```ts
+@Entity("Users")
+export class User {
+	@PrimaryGeneratedColumn("uuid")
+	id!: string;
+
+	@Column()
+	name!: string;
+}
+```
+
+### Explicit Primary Key
+
+Use `@PrimaryColumn()` when the application provides the primary key:
+
+```ts
+@Entity("Users")
+export class User {
+	@PrimaryColumn()
+	id!: string;
+
+	@Column()
+	name!: string;
+}
+```
+
+Primary key values must be unique within the worksheet.
+
+The driver does not provide database-level primary key enforcement like a relational database. Primary key validation is performed by the driver during supported operations.
+
+---
+
+## Column Options
+
+Standard TypeORM column options can be used where supported by the driver.
+
+For example:
+
+```ts
+@Column({
+    nullable: true,
+})
+description!: string | null;
+```
+
+Default values are also supported:
+
+```ts
+@Column({
+    default: true,
+})
+active!: boolean;
+```
+
+The driver applies the configured default when inserting entities where the value is not explicitly provided.
+
+---
+
+## Custom Column Names
+
+TypeORM column names can be customized using the `name` option:
+
+```ts
+@Entity("Users")
+export class User {
+	@PrimaryGeneratedColumn()
+	id!: number;
+
+	@Column({
+		name: "full_name"
+	})
+	name!: string;
+}
+```
+
+The worksheet will use:
+
+| id  | full_name |
+| --- | --------- |
+| 1   | Budi      |
+
+The entity property remains `name`:
+
+```ts
+user.name;
+```
+
+while the worksheet column is:
+
+```text
+full_name
+```
+
+Column names are resolved through TypeORM's entity metadata.
+
+---
+
+## Date Columns
+
+`Date` columns are supported:
+
+```ts
+@Entity("Users")
+export class User {
+	@PrimaryGeneratedColumn()
+	id!: number;
+
+	@Column()
+	name!: string;
+
+	@Column()
+	createdAt!: Date;
+}
+```
+
+When reading data, the driver hydrates the worksheet value into a JavaScript `Date` according to the column metadata.
+
+---
+
+## Soft Delete
+
+Soft-delete entities can use TypeORM's `@DeleteDateColumn()`:
+
+```ts
+import { Entity, PrimaryGeneratedColumn, Column, DeleteDateColumn } from "typeorm";
+
+@Entity("Users")
+export class User {
+	@PrimaryGeneratedColumn()
+	id!: number;
+
+	@Column()
+	name!: string;
+
+	@DeleteDateColumn({
+		nullable: true
+	})
+	deletedAt!: Date | null;
+}
+```
+
+The driver supports:
+
+- `@DeleteDateColumn()`
+- `softDelete()`
+- `softRemove()`
+- `restore()`
+- Excluding soft-deleted rows from normal queries
+- Including soft-deleted rows with `withDeleted`
+
+For example:
+
+```ts
+await userRepository.softDelete(user.id);
+```
+
+Normal queries will exclude the soft-deleted entity:
+
+```ts
+const users = await userRepository.find();
+```
+
+To include soft-deleted entities:
+
+```ts
+const users = await userRepository.find({
+	withDeleted: true
+});
+```
+
+See [CRUD Operations](crud.md) for more information.
+
+---
+
+## Relations
+
+TypeORM relation metadata can be used with Google Sheets.
+
+For example:
+
+```ts
+@Entity("Users")
+export class User {
+	@PrimaryGeneratedColumn()
+	id!: number;
+
+	@Column()
+	name!: string;
+
+	@OneToMany(() => Post, (post) => post.user)
+	posts!: Post[];
+}
+
+@Entity("Posts")
+export class Post {
+	@PrimaryGeneratedColumn()
+	id!: number;
+
+	@Column()
+	title!: string;
+
+	@Column()
+	userId!: number;
+
+	@ManyToOne(() => User, (user) => user.posts)
+	@JoinColumn({
+		name: "userId"
+	})
+	user!: User;
+}
+```
+
+The `Posts` worksheet stores the foreign-key value in the `userId` column.
+
+An explicit foreign-key value can be persisted normally:
+
+```ts
+post.userId = user.id;
+
+await postRepository.save(post);
+```
+
+Relations can also be loaded explicitly:
+
+```ts
+const users = await userRepository.find({
+	relations: {
+		posts: true
+	}
+});
+```
+
+Supported relation features include:
+
+- `@ManyToOne`
+- `@OneToMany`
+- `@JoinColumn`
+- Explicit foreign-key column persistence
+- Explicit relation loading
+- Relation queries through supported joins
+- Soft-delete filtering for relations
+- `withDeleted` relation loading
+
+Nested relation persistence and cascade persistence are not fully supported.
+
+For example, applications should not rely on automatically persisting a nested relation through:
+
+```ts
+await userRepository.save({
+	name: "Budi",
+	posts: [
+		{
+			title: "Post 1"
+		}
+	]
+});
+```
+
+Applications should explicitly persist related entities when necessary.
+
+---
+
+## Naming Strategies
+
+Entity and column names are resolved through TypeORM metadata.
+
+The driver does not implement a separate naming-strategy system. TypeORM-generated metadata is used to determine the worksheet and column names.
+
+---
+
+## Entity Metadata
+
+Entity definitions are processed by TypeORM before the Google Sheets driver handles them.
+
+The driver consumes TypeORM's `EntityMetadata`, including information such as:
+
+- Entity name
+- Worksheet name
+- Column names
+- Column types
+- Primary columns
+- Generated columns
+- Delete-date columns
+- Relations
+- Join columns
+- Nullable columns
+- Default values
+
+This means entity definitions remain standard TypeORM entity definitions rather than using a Google Sheets-specific schema format.
+
+---
+
+## Example
+
+A complete entity setup might look like:
+
+```ts
+import { Column, DeleteDateColumn, Entity, JoinColumn, ManyToOne, OneToMany, PrimaryGeneratedColumn } from "typeorm";
+
+@Entity("Users")
+export class User {
+	@PrimaryGeneratedColumn()
+	id!: number;
+
+	@Column()
+	name!: string;
+
+	@Column()
+	active!: boolean;
+
+	@DeleteDateColumn({
+		nullable: true
+	})
+	deletedAt!: Date | null;
+
+	@OneToMany(() => Post, (post) => post.user)
+	posts!: Post[];
+}
+
+@Entity("Posts")
+export class Post {
+	@PrimaryGeneratedColumn()
+	id!: number;
+
+	@Column()
+	title!: string;
+
+	@Column()
+	userId!: number;
+
+	@DeleteDateColumn({
+		nullable: true
+	})
+	deletedAt!: Date | null;
+
+	@ManyToOne(() => User, (user) => user.posts)
+	@JoinColumn({
+		name: "userId"
+	})
+	user!: User;
+}
+```
+
+This definition can be used directly with a TypeORM `DataSource` configured for the Google Sheets driver.
+
+## Limitations
+
+Entity definitions use TypeORM metadata, but not every TypeORM feature can be represented by Google Sheets.
+
+In particular:
+
+- Transactions are not supported.
+- Foreign-key constraints are not enforced by Google Sheets.
+- Database-level cascade operations are not available.
+- Nested relation persistence and full cascade persistence are not fully supported.
+- Lazy relation loading is not supported.
+- Relational database guarantees such as referential integrity are not provided.
+
+See [Supported Features](supported-features.md) and [Limitations](limitations.md) for the complete compatibility details.
+
+```
+
+Ini sudah saya buat sebagai **`docs/entities.md`** dan sengaja tidak memasukkan detail CRUD terlalu jauh supaya dokumentasinya tidak tumpang tindih dengan `crud.md`.
+```