tantan-typeorm-gs 1.0.0

package/docs/contributing.md

@@ -0,0 +1,177 @@
+## Contribution Guide
+
+Contributions to `tantan-typeorm-gs` should preserve compatibility with TypeORM while keeping the Google Sheets-specific implementation predictable and testable.
+
+### Before Contributing
+
+Before making changes:
+
+1. Understand the existing architecture.
+2. Check whether the requested behavior is already supported.
+3. Identify the layer responsible for the change.
+4. Review existing tests related to that behavior.
+5. Avoid modifying unrelated code.
+
+The project favors small, focused changes over broad refactoring.
+
+### Development Workflow
+
+A typical contribution workflow is:
+
+```text
+Understand
+    ↓
+Identify affected layer
+    ↓
+Add or update focused test
+    ↓
+Implement change
+    ↓
+Run focused test
+    ↓
+Run typecheck
+    ↓
+Run full test suite
+    ↓
+Update documentation
+```
+
+### Tests First
+
+New behavior should have an appropriate test.
+
+Use the existing test layer that matches the behavior being changed.
+
+| Change                         | Preferred test         |
+| ------------------------------ | ---------------------- |
+| Repository behavior            | Repository test        |
+| QueryRunner behavior           | QueryRunner test       |
+| Query interpretation           | Query/interpreter test |
+| Google Sheets API behavior     | API integration test   |
+| Performance-sensitive behavior | Performance test       |
+
+Do not add duplicate tests when an existing test already covers the same behavior.
+
+### Preserve Existing Behavior
+
+The existing test suite represents supported behavior and compatibility expectations.
+
+A contribution should not modify an existing base test merely to make a new implementation pass.
+
+If a new feature causes an existing test to fail:
+
+1. Determine whether the existing behavior is actually incorrect.
+2. Determine whether the new implementation introduced a regression.
+3. Fix the implementation when the regression is real.
+4. Change an existing test only when the intended public behavior has genuinely changed.
+
+### Google API Tests
+
+Tests that communicate with the real Google Sheets API should remain separate from normal driver tests.
+
+Real API tests require appropriate Google credentials and a dedicated test spreadsheet.
+
+Do not commit:
+
+- service-account private keys
+- credential JSON files
+- spreadsheet secrets
+- environment files containing credentials
+- production spreadsheet identifiers when they are sensitive
+
+### Pull Requests
+
+A pull request should clearly describe:
+
+- what changed
+- why the change is required
+- which layer was modified
+- which tests were added or changed
+- how the change was verified
+- whether documentation was updated
+
+Keep pull requests focused.
+
+Unrelated formatting changes, refactoring, or dependency changes should not be mixed into a feature or bug-fix contribution unless they are necessary.
+
+### Verification
+
+Before submitting a contribution, run:
+
+```bash id="8k4m2p"
+bun run typecheck
+bun test
+```
+
+When relevant, also run the specific integration or performance test:
+
+```bash id="5v9n1x"
+bun test test/google-sheets/0001-client.test.ts
+bun test test/google-sheets/0007-performance.test.ts
+```
+
+All relevant tests should pass before the contribution is submitted.
+
+### Documentation
+
+If a contribution changes supported behavior, update the appropriate documentation.
+
+Examples include:
+
+- adding a new supported TypeORM feature
+- changing configuration behavior
+- adding a new limitation
+- changing authentication requirements
+- changing performance characteristics
+- adding or removing Google Sheets API capabilities
+
+Documentation should describe behavior that is actually implemented and tested.
+
+### Unsupported Features
+
+Do not silently emulate unsupported relational-database behavior.
+
+For example, Google Sheets does not provide database transactions or database-level foreign-key enforcement.
+
+If a TypeORM feature cannot be meaningfully supported by Google Sheets, it should either remain unsupported or be explicitly documented as a driver limitation.
+
+### Code Quality
+
+Contributions should:
+
+- use TypeScript consistently
+- preserve the existing ESM module structure
+- follow the existing naming conventions
+- avoid unnecessary abstractions
+- keep error handling explicit
+- avoid unnecessary production changes
+- maintain the separation between the driver and Google Sheets API client
+
+### Contribution Checklist
+
+```text
+[ ] The affected layer has been identified
+[ ] Existing behavior and tests have been reviewed
+[ ] Focused tests cover the change
+[ ] No unrelated tests were modified
+[ ] TypeScript typecheck passes
+[ ] Full test suite passes
+[ ] Integration tests pass when applicable
+[ ] Performance impact has been considered when applicable
+[ ] Documentation has been updated when necessary
+[ ] No credentials or sensitive data are included
+[ ] The contribution is focused and minimal
+```
+
+### Summary
+
+The goal of contributions is not simply to make a feature work, but to maintain a stable TypeORM-compatible driver with predictable Google Sheets behavior.
+
+Contributors should prioritize:
+
+- compatibility
+- tested behavior
+- minimal changes
+- clear separation of concerns
+- explicit limitations
+- maintainable documentation

package/docs/crud.md

@@ -0,0 +1,351 @@
+## CRUD Examples
+
+`tantan-typeorm-gs` exposes the standard TypeORM repository API for supported CRUD operations.
+
+The examples below assume the following entity:
+
+```ts
+import { Column, Entity, PrimaryGeneratedColumn } from "typeorm";
+
+@Entity("users")
+class User {
+	@PrimaryGeneratedColumn()
+	id!: number;
+
+	@Column()
+	name!: string;
+
+	@Column()
+	email!: string;
+}
+```
+
+After initializing the data source:
+
+```ts
+await dataSource.initialize();
+
+const repository = dataSource.getRepository(User);
+```
+
+### Create
+
+#### Insert One Row
+
+Use `repository.insert()` to insert a new row:
+
+```ts
+const result = await repository.insert({
+	name: "Budi",
+	email: "budi@example.com"
+});
+```
+
+For an entity with an auto-generated primary key, the driver generates the ID automatically.
+
+#### Insert Multiple Rows
+
+Multiple rows can be inserted in a single repository operation:
+
+```ts
+await repository.insert([
+	{
+		name: "Budi",
+		email: "budi@example.com"
+	},
+	{
+		name: "Siti",
+		email: "siti@example.com"
+	},
+	{
+		name: "Andi",
+		email: "andi@example.com"
+	}
+]);
+```
+
+The driver processes the rows as a batch operation.
+
+#### Save
+
+`repository.save()` can also be used:
+
+```ts
+const user = repository.create({
+	name: "Budi",
+	email: "budi@example.com"
+});
+
+await repository.save(user);
+```
+
+`save()` follows TypeORM's repository semantics for determining whether the entity should be inserted or updated.
+
+### Read
+
+#### Find All Rows
+
+Use `repository.find()` to retrieve all rows:
+
+```ts
+const users = await repository.find();
+```
+
+The result is an array of entity instances:
+
+```ts
+for (const user of users) {
+	console.log(user.id, user.name, user.email);
+}
+```
+
+#### Find One Row
+
+A specific row can be retrieved using `findOne()`:
+
+```ts
+const user = await repository.findOne({
+	where: {
+		id: 1
+	}
+});
+```
+
+If no matching row exists, the result is `null`.
+
+```ts
+if (!user) {
+	console.log("User not found.");
+}
+```
+
+#### Find by Conditions
+
+Multiple conditions can be supplied:
+
+```ts
+const users = await repository.find({
+	where: {
+		name: "Budi"
+	}
+});
+```
+
+The available filtering capabilities are covered in the **Find Options** section.
+
+### Update
+
+Use `repository.update()` to update rows matching a condition:
+
+```ts
+await repository.update(
+	{
+		id: 1
+	},
+	{
+		name: "Budi Updated"
+	}
+);
+```
+
+The first argument specifies which rows should be updated.
+
+The second argument contains the values to update.
+
+Multiple rows can be affected when the condition matches multiple records.
+
+### Delete
+
+Use `repository.delete()` to delete rows matching a condition:
+
+```ts
+await repository.delete({
+	id: 1
+});
+```
+
+The operation removes the matching row from the worksheet.
+
+A condition should be supplied when deleting data to avoid unintentionally deleting more rows than intended.
+
+### Remove Entity
+
+An entity instance can also be removed using `repository.remove()`:
+
+```ts
+const user = await repository.findOne({
+	where: {
+		id: 1
+	}
+});
+
+if (user) {
+	await repository.remove(user);
+}
+```
+
+`remove()` operates on an entity instance, while `delete()` operates directly from a deletion condition.
+
+### Update Using an Entity
+
+An existing entity can be modified and persisted using `save()`:
+
+```ts
+const user = await repository.findOne({
+	where: {
+		id: 1
+	}
+});
+
+if (user) {
+	user.name = "Budi Updated";
+
+	await repository.save(user);
+}
+```
+
+This is useful when the application already has the entity instance and wants TypeORM to persist its changes.
+
+### Generated IDs
+
+For an entity using:
+
+```ts
+@PrimaryGeneratedColumn()
+id!: number;
+```
+
+the ID does not need to be supplied when creating a new row:
+
+```ts
+await repository.insert({
+	name: "Budi",
+	email: "budi@example.com"
+});
+```
+
+The driver assigns the generated primary key.
+
+An explicitly supplied generated ID is also preserved:
+
+```ts
+await repository.insert({
+	id: 100,
+	name: "Budi",
+	email: "budi@example.com"
+});
+```
+
+If the supplied primary key already exists, the driver rejects the operation as a duplicate primary-key insert.
+
+### Manually Assigned Primary Keys
+
+For an entity using:
+
+```ts
+@PrimaryColumn()
+id!: number;
+```
+
+the primary key must be supplied:
+
+```ts
+await repository.insert({
+	id: 1,
+	name: "Budi",
+	email: "budi@example.com"
+});
+```
+
+An insert without the required primary key is rejected.
+
+### Lifecycle Hooks
+
+CRUD operations participate in supported TypeORM entity lifecycle events.
+
+For example:
+
+```ts
+@BeforeInsert()
+beforeInsert()
+{
+    this.name =
+        this.name.toUpperCase();
+}
+```
+
+When the entity is inserted, the lifecycle hook is executed as part of the TypeORM operation.
+
+Subscribers are also supported for the corresponding lifecycle events.
+
+See the **Supported Features** section for the supported lifecycle behavior.
+
+### Complete Example
+
+A simple application can perform a complete CRUD flow:
+
+```ts
+const dataSource = createGoogleSheetsDataSource({
+	type: "google-sheets",
+
+	spreadsheetId: process.env.GOOGLE_SHEETS_SPREADSHEET_ID!,
+
+	credentials: {
+		clientEmail: process.env.GOOGLE_SHEETS_CLIENT_EMAIL!,
+
+		privateKey: process.env.GOOGLE_SHEETS_PRIVATE_KEY!
+	},
+
+	entities: [User]
+});
+
+await dataSource.initialize();
+
+const repository = dataSource.getRepository(User);
+
+// Create
+const user = await repository.save({
+	name: "Budi",
+	email: "budi@example.com"
+});
+
+// Read
+const found = await repository.findOne({
+	where: {
+		id: user.id
+	}
+});
+
+// Update
+await repository.update(
+	{
+		id: user.id
+	},
+	{
+		name: "Budi Updated"
+	}
+);
+
+// Delete
+await repository.delete({
+	id: user.id
+});
+
+await dataSource.destroy();
+```
+
+### CRUD Mapping
+
+The common repository operations can be summarized as:
+
+| Operation           | Repository API        |
+| ------------------- | --------------------- |
+| Create one          | `insert()` / `save()` |
+| Create multiple     | `insert()`            |
+| Read multiple       | `find()`              |
+| Read one            | `findOne()`           |
+| Update              | `update()` / `save()` |
+| Delete by condition | `delete()`            |
+| Delete entity       | `remove()`            |
+
+These APIs operate through the Google Sheets driver and are subject to the driver's supported TypeORM behavior and Google Sheets limitations.

package/docs/custom-client.md

@@ -0,0 +1,165 @@
+## Custom Client
+
+The Google Sheets driver allows applications to provide a custom `GoogleSheetsClient`.
+
+This is useful when the application needs to control how Google Sheets data is accessed, for example for testing, mocking, caching, or implementing a custom integration.
+
+### Default Client
+
+If no custom client is provided, the data source creates its own `GoogleSheetsApiClient` using the configured spreadsheet ID and credentials.
+
+```ts
+const dataSource = createGoogleSheetsDataSource({
+	type: "google-sheets",
+
+	spreadsheetId: process.env.GOOGLE_SHEETS_SPREADSHEET_ID!,
+
+	credentials: {
+		clientEmail: process.env.GOOGLE_SHEETS_CLIENT_EMAIL!,
+
+		privateKey: process.env.GOOGLE_SHEETS_PRIVATE_KEY!
+	},
+
+	entities: [User]
+});
+```
+
+The default flow is:
+
+```text
+createGoogleSheetsDataSource()
+        ↓
+client not provided
+        ↓
+GoogleSheetsApiClient
+        ↓
+Google Sheets API
+```
+
+### Providing a Custom Client
+
+A custom client can be supplied through the `client` option:
+
+```ts
+const client = new MyGoogleSheetsClient();
+
+const dataSource = createGoogleSheetsDataSource({
+	type: "google-sheets",
+
+	spreadsheetId: process.env.GOOGLE_SHEETS_SPREADSHEET_ID!,
+
+	credentials: {
+		clientEmail: process.env.GOOGLE_SHEETS_CLIENT_EMAIL!,
+
+		privateKey: process.env.GOOGLE_SHEETS_PRIVATE_KEY!
+	},
+
+	client,
+
+	entities: [User]
+});
+```
+
+When `client` is provided, the driver uses that client instead of creating a default `GoogleSheetsApiClient`.
+
+```text
+createGoogleSheetsDataSource()
+        ↓
+client provided?
+   ┌────┴────┐
+  yes       no
+   ↓         ↓
+custom    GoogleSheetsApiClient
+client
+   ↓         ↓
+   └────┬────┘
+        ↓
+GoogleSheetsDriver
+```
+
+### Custom Client Interface
+
+A custom client must implement the `GoogleSheetsClient` interface expected by the driver.
+
+For example:
+
+```ts
+import type { GoogleSheetsClient } from "tantan-typeorm-gs";
+
+class MyGoogleSheetsClient implements GoogleSheetsClient {
+	// Implement the required client methods.
+}
+```
+
+The exact methods depend on the operations used by the driver.
+
+A custom client therefore allows the driver layer to remain independent from the actual Google Sheets transport implementation.
+
+### Testing with a Fake Client
+
+A custom client is particularly useful for tests.
+
+For example:
+
+```ts
+const client = new Memory({
+	users: [
+		{
+			id: 1,
+			name: "Budi"
+		}
+	]
+});
+
+const dataSource = createGoogleSheetsDataSource({
+	type: "google-sheets",
+
+	client,
+
+	entities: [User]
+});
+
+await dataSource.initialize();
+
+const repository = dataSource.getRepository(User);
+
+const users = await repository.find();
+```
+
+This allows repository and driver behavior to be tested without making requests to the Google Sheets API.
+
+### Custom Client Precedence
+
+When `client` is supplied:
+
+```ts
+client;
+```
+
+takes precedence over the default API client.
+
+The credentials and spreadsheet ID are still part of the data source configuration, but the custom client is the client instance used by the driver.
+
+### When to Use a Custom Client
+
+A custom client is useful for:
+
+- unit and integration tests
+- fake or in-memory spreadsheet data
+- custom authentication handling
+- request logging
+- caching
+- retry policies
+- alternative Google Sheets transport implementations
+
+For normal production usage, the default `GoogleSheetsApiClient` is sufficient when direct Google Sheets API access is required.
+
+### Summary
+
+| Configuration                    | Client used                                    |
+| -------------------------------- | ---------------------------------------------- |
+| `client` omitted                 | `GoogleSheetsApiClient`                        |
+| `client` provided                | Provided `GoogleSheetsClient`                  |
+| `client` provided with fake data | Useful for testing without Google API requests |
+
+The custom client is injected at data source creation time and is used by the `GoogleSheetsDriver`.