tantan-typeorm-gs 1.0.0

package/docs/find-options.md

@@ -0,0 +1,296 @@
+## Find Options
+
+`tantan-typeorm-gs` supports TypeORM find options for filtering, ordering, and limiting query results.
+
+The options are passed directly to repository methods such as `find()`, `findOne()`, `findAndCount()`, and `count()`.
+
+### Where
+
+Use `where` to filter rows.
+
+```ts
+const users = await repository.find({
+	where: {
+		name: "Budi"
+	}
+});
+```
+
+Multiple properties can be specified:
+
+```ts
+const users = await repository.find({
+	where: {
+		name: "Budi",
+		email: "budi@example.com"
+	}
+});
+```
+
+The conditions are evaluated against the corresponding worksheet columns.
+
+### OR Conditions
+
+Multiple `where` objects can be supplied to express OR conditions:
+
+```ts
+const users = await repository.find({
+	where: [
+		{
+			name: "Budi"
+		},
+		{
+			name: "Siti"
+		}
+	]
+});
+```
+
+This returns rows matching either condition.
+
+Conceptually:
+
+```text
+name = 'Budi'
+OR
+name = 'Siti'
+```
+
+### Order
+
+Use `order` to sort the result.
+
+```ts
+const users = await repository.find({
+	order: {
+		name: "ASC"
+	}
+});
+```
+
+Descending order:
+
+```ts
+const users = await repository.find({
+	order: {
+		name: "DESC"
+	}
+});
+```
+
+Multiple fields can be specified:
+
+```ts
+const users = await repository.find({
+	order: {
+		name: "ASC",
+		email: "DESC"
+	}
+});
+```
+
+The ordering is applied to the returned result rather than changing the underlying worksheet.
+
+### Skip
+
+Use `skip` to ignore a number of matching rows from the beginning of the result.
+
+```ts
+const users = await repository.find({
+	skip: 10
+});
+```
+
+For example, with:
+
+```text
+skip: 10
+```
+
+the first 10 matching rows are omitted from the returned result.
+
+### Take
+
+Use `take` to limit the number of returned rows.
+
+```ts
+const users = await repository.find({
+	take: 10
+});
+```
+
+This returns at most 10 rows.
+
+### Pagination
+
+`skip` and `take` can be combined to implement offset-based pagination:
+
+```ts
+const page = 2;
+const pageSize = 10;
+
+const users = await repository.find({
+	skip: (page - 1) * pageSize,
+	take: pageSize
+});
+```
+
+For page 2 with a page size of 10:
+
+```text
+skip = 10
+take = 10
+```
+
+The dedicated **Pagination** section provides a more complete example.
+
+### Combining Options
+
+Find options can be combined:
+
+```ts
+const users = await repository.find({
+	where: {
+		name: "Budi"
+	},
+
+	order: {
+		email: "ASC"
+	},
+
+	skip: 10,
+
+	take: 10
+});
+```
+
+The operation can therefore:
+
+1. filter matching rows
+2. order the result
+3. skip rows
+4. limit the returned rows
+
+### Find One
+
+`findOne()` accepts the same style of find options:
+
+```ts
+const user = await repository.findOne({
+	where: {
+		id: 1
+	}
+});
+```
+
+Ordering can also be supplied when selecting a single result:
+
+```ts
+const user = await repository.findOne({
+	where: {
+		name: "Budi"
+	},
+
+	order: {
+		id: "ASC"
+	}
+});
+```
+
+If no matching entity exists, `findOne()` returns `null`.
+
+### Find and Count
+
+Use `findAndCount()` when both the result set and the total number of matching rows are required.
+
+```ts
+const [users, total] = await repository.findAndCount({
+	where: {
+		name: "Budi"
+	}
+});
+```
+
+The result contains:
+
+```text
+users
+total
+```
+
+`skip` and `take` can be used to limit the returned entities while the count represents the total matching entities.
+
+For example:
+
+```ts
+const [users, total] = await repository.findAndCount({
+	where: {
+		name: "Budi"
+	},
+
+	skip: 10,
+
+	take: 10
+});
+```
+
+This allows the application to implement pagination while still knowing the total number of matching rows.
+
+### Count
+
+Use `count()` to count matching entities:
+
+```ts
+const total = await repository.count({
+	where: {
+		name: "Budi"
+	}
+});
+```
+
+The count is based on the matching rows.
+
+`skip` and `take` should not be used when the intention is to obtain the total number of matching entities.
+
+### Example
+
+A typical paginated search can be written as:
+
+```ts
+const page = 1;
+const pageSize = 20;
+
+const [users, total] = await repository.findAndCount({
+	where: {
+		name: "Budi"
+	},
+
+	order: {
+		name: "ASC"
+	},
+
+	skip: (page - 1) * pageSize,
+
+	take: pageSize
+});
+
+console.log("Total:", total);
+console.log("Rows:", users);
+```
+
+### Supported Find Options
+
+The currently supported and tested find-option behavior includes:
+
+| Option           | Purpose                           |
+| ---------------- | --------------------------------- |
+| `where`          | Filter rows                       |
+| `where: []`      | OR conditions                     |
+| `order`          | Sort results                      |
+| `skip`           | Offset results                    |
+| `take`           | Limit results                     |
+| `findOne()`      | Retrieve one matching entity      |
+| `findAndCount()` | Retrieve entities and total count |
+| `count()`        | Count matching entities           |
+
+More advanced TypeORM find operators should only be considered supported when explicitly implemented and tested by the driver.

package/docs/google-cloud.md

@@ -0,0 +1,101 @@
+## Google Cloud Setup
+
+`tantan-typeorm-gs` uses the Google Sheets API to read and modify spreadsheet data.
+
+The recommended setup for this driver is a **Google Cloud service account** with access to the target Google Spreadsheet.
+
+### 1. Create a Google Cloud Project
+
+Create or select a project in Google Cloud Console.
+
+The project will be used to manage the Google Sheets API and the service account used by the application.
+
+### 2. Enable Google Sheets API
+
+Open the **API Library** in Google Cloud Console and enable:
+
+```text
+Google Sheets API
+```
+
+The API service name is:
+
+```text
+sheets.googleapis.com
+```
+
+Google Cloud requires the corresponding API to be enabled before an application can use it.
+
+### 3. Create a Service Account
+
+Open:
+
+```text
+IAM & Admin → Service Accounts
+```
+
+Create a new service account for the application.
+
+For example:
+
+```text
+tantan-typeorm-gs
+```
+
+A service account represents the application rather than an individual Google user and can be granted access to Google Cloud resources.
+
+After creating the service account, note its email address:
+
+```text
+tantan-typeorm-gs@YOUR_PROJECT_ID.iam.gserviceaccount.com
+```
+
+### 4. Create Service Account Credentials
+
+For local development, create a service account key in JSON format from the service account's **Keys** section.
+
+The generated credential contains sensitive information, including the private key.
+
+**Do not commit the JSON key to Git.**
+
+Google notes that user-managed service account keys are long-lived credentials and should be handled carefully. For workloads running on Google Cloud or supported external environments, more secure alternatives such as attached service accounts or Workload Identity Federation should be considered.
+
+### 5. Share the Spreadsheet
+
+Open the Google Spreadsheet that will be used by the application.
+
+Share the spreadsheet with the service account email:
+
+```text
+tantan-typeorm-gs@YOUR_PROJECT_ID.iam.gserviceaccount.com
+```
+
+Grant the service account the required access level.
+
+For this driver, the service account must be able to access the spreadsheet and perform the operations required by the application. Google also documents sharing the spreadsheet directly with the service account as part of Sheets API service-account setup.
+
+### 6. Get the Spreadsheet ID
+
+The spreadsheet ID is part of the Google Sheets URL:
+
+```text
+https://docs.google.com/spreadsheets/d/SPREADSHEET_ID/edit
+```
+
+For example:
+
+```text
+https://docs.google.com/spreadsheets/d/1AbCdEfGhIjKlMnOpQrStUvWxYz/edit
+```
+
+The spreadsheet ID is:
+
+```text
+1AbCdEfGhIjKlMnOpQrStUvWxYz
+```
+
+This value is passed to the driver's configuration.
+
+### Next Step
+
+After Google Cloud and spreadsheet access have been configured, configure the driver's authentication credentials in the application.

package/docs/installation.md

@@ -0,0 +1,51 @@
+## Installation
+
+### Requirements
+
+Before installing `tantan-typeorm-gs`, make sure your project has:
+
+- Node.js or Bun
+- TypeScript
+- TypeORM `1.1.x`
+
+The driver is distributed as an npm package and uses TypeORM as its ORM layer.
+
+### Install
+
+Using npm:
+
+```bash
+npm install tantan-typeorm-gs typeorm googleapis
+```
+
+Using Bun:
+
+```bash
+bun add tantan-typeorm-gs typeorm googleapis
+```
+
+### TypeScript
+
+The project using the driver should have TypeScript configured.
+
+For example:
+
+```json
+{
+	"compilerOptions": {
+		"target": "ES2022",
+		"module": "ESNext",
+		"moduleResolution": "Bundler"
+	}
+}
+```
+
+### Verify Installation
+
+After installation, the package can be imported from the application:
+
+```ts
+import { createGoogleSheetsDataSource } from "tantan-typeorm-gs";
+```
+
+The next step is configuring Google Cloud and Google Sheets API access.

package/docs/integration-testing.md

@@ -0,0 +1,178 @@
+## Integration Testing
+
+The project includes integration tests for validating the Google Sheets API client against the real Google Sheets API.
+
+Integration tests are different from the unit and driver-level tests that use `Memory`.
+
+### Test Layers
+
+The test suite can be viewed in several layers:
+
+```text
+Unit / Driver Tests
+        ↓
+Memory
+        ↓
+GoogleSheetsDriver
+        ↓
+Repository / QueryRunner
+
+Integration Tests
+        ↓
+GoogleSheetsApiClient
+        ↓
+Google Sheets API
+        ↓
+Real Spreadsheet
+```
+
+The fake client is used for fast and deterministic tests.
+
+The integration tests validate the behavior of the actual Google Sheets API client.
+
+### Fake Client Tests
+
+Most driver behavior can be tested without network access:
+
+```ts id="8r3m1v"
+const client = new Memory({
+	users: []
+});
+
+const dataSource = createGoogleSheetsDataSource({
+	type: "google-sheets",
+
+	client,
+
+	entities: [User]
+});
+```
+
+This approach is useful for testing:
+
+- repository operations
+- query execution
+- metadata handling
+- lifecycle hooks
+- subscribers
+- generated primary keys
+- error handling
+- pagination and sorting
+- driver behavior
+
+These tests should remain fast and deterministic.
+
+### Google Sheets API Integration Tests
+
+The Google Sheets API client has dedicated integration coverage.
+
+The integration tests exercise operations against the actual Google Sheets API, including:
+
+- reading rows
+- inserting rows
+- updating rows
+- deleting rows
+- batch-compatible operations
+- handling Google API responses
+
+The test file is:
+
+```text id="3q7m9x"
+test/google-sheets/0001-client.test.ts
+```
+
+### Required Configuration
+
+Integration tests require valid Google Cloud credentials and access to a test spreadsheet.
+
+The test environment should provide the required configuration without committing credentials to the repository.
+
+For example:
+
+```env id="6v2k4p"
+GOOGLE_SHEETS_SPREADSHEET_ID=...
+GOOGLE_SHEETS_CLIENT_EMAIL=...
+GOOGLE_SHEETS_PRIVATE_KEY=...
+```
+
+The service account must have access to the spreadsheet used by the integration tests.
+
+### Keep Integration Data Isolated
+
+A dedicated spreadsheet should be used for integration testing whenever possible.
+
+The test spreadsheet should not contain production data.
+
+Integration tests may modify worksheet contents, so the test environment should be isolated from important spreadsheets.
+
+### Running Integration Tests
+
+Run the API client integration test directly:
+
+```bash id="1m8x5c"
+bun test test/google-sheets/0001-client.test.ts
+```
+
+The integration test suite currently contains coverage for the Google Sheets API client and batch operations.
+
+### Unit Tests vs Integration Tests
+
+Use the fake client when the behavior being tested belongs to the driver:
+
+```text id="7q3n8v"
+Driver behavior
+    ↓
+Memory
+```
+
+Use the real API integration test when validating the Google API client itself:
+
+```text id="5c1m7x"
+GoogleSheetsApiClient
+    ↓
+Google Sheets API
+```
+
+This separation prevents network availability or Google API latency from affecting the majority of the test suite.
+
+### Recommended Development Workflow
+
+During normal development:
+
+```bash id="9v4k2m"
+bun test
+```
+
+should be used for the regular test suite.
+
+When changing the Google Sheets API client, run the dedicated integration tests as well:
+
+```bash id="2x7p5n"
+bun test test/google-sheets/0001-client.test.ts
+```
+
+Performance tests can be run separately:
+
+```bash id="6k3m8q"
+bun test test/google-sheets/0007-performance.test.ts
+```
+
+### Security
+
+Never commit integration-test credentials to source control.
+
+Use environment variables or the project's secure CI/CD secret mechanism.
+
+Integration-test spreadsheets should also be treated as test infrastructure and should not contain sensitive production information.
+
+### Summary
+
+The project intentionally separates testing responsibilities:
+
+| Test type               | Client                  | Purpose                           |
+| ----------------------- | ----------------------- | --------------------------------- |
+| Driver/repository tests | `Memory`                | Fast driver behavior testing      |
+| API integration tests   | `GoogleSheetsApiClient` | Real Google Sheets API validation |
+| Performance tests       | `Memory`                | Driver regression baseline        |
+
+This separation keeps the normal test suite fast while still providing coverage against the real Google Sheets API.