tantan-typeorm-gs 1.0.0

package/docs/performance.md

@@ -0,0 +1,171 @@
+## Performance Considerations
+
+Google Sheets is an API-based spreadsheet service rather than a database engine.
+
+The performance of the driver therefore depends on several factors, including worksheet size, number of API requests, operation type, and network latency.
+
+### Avoid Treating Google Sheets as a Large Database
+
+The driver is intended for workloads where Google Sheets is an appropriate data store.
+
+For large datasets or high-frequency database workloads, a relational database is generally more appropriate.
+
+Operations such as:
+
+```ts id="8m2q5v"
+const users = await repository.find();
+```
+
+may require processing a significant number of worksheet rows.
+
+Applications should avoid loading an entire large worksheet when only a small subset of data is required.
+
+### Use Filtering
+
+When only specific records are required, use `where` conditions:
+
+```ts id="4x7n1c"
+const users = await repository.find({
+	where: {
+		status: "active"
+	}
+});
+```
+
+This avoids unnecessarily returning unrelated records to the application.
+
+### Use Pagination
+
+For user-facing lists, combine filtering, sorting, and pagination:
+
+```ts id="9p3k6w"
+const page = 1;
+const pageSize = 20;
+
+const users = await repository.find({
+	where: {
+		status: "active"
+	},
+
+	order: {
+		id: "ASC"
+	},
+
+	skip: (page - 1) * pageSize,
+
+	take: pageSize
+});
+```
+
+Pagination limits the number of records returned to the application at once.
+
+However, `skip` and `take` should not be considered equivalent to indexed database pagination.
+
+### Prefer Batch Operations
+
+When multiple records need to be modified, use repository operations that allow the driver to process multiple rows together.
+
+For example:
+
+```ts id="6v4m8q"
+await repository.insert([
+	{
+		name: "Budi"
+	},
+	{
+		name: "Andi"
+	},
+	{
+		name: "Citra"
+	}
+]);
+```
+
+The Google Sheets API client supports batching compatible operations to reduce unnecessary API requests.
+
+### Minimize API Requests
+
+The default `GoogleSheetsApiClient` communicates with Google Sheets through the Google Sheets API.
+
+Network requests generally have significantly higher overhead than in-memory operations.
+
+Applications should therefore avoid unnecessarily repeating operations such as:
+
+```ts id="1c5x7m"
+await repository.find();
+await repository.find();
+await repository.find();
+```
+
+when the same result can safely be reused by the application.
+
+### Custom Client for Specialized Workloads
+
+Applications with specialized performance requirements can provide a custom `GoogleSheetsClient`.
+
+A custom client can implement application-specific strategies such as:
+
+- caching
+- request batching
+- retry handling
+- request deduplication
+- custom transport behavior
+
+The driver remains independent of those implementation details.
+
+### Performance Baseline
+
+The project's automated performance tests include a basic baseline using `Memory`.
+
+The current baseline tested:
+
+| Operation |    Dataset |    Result |
+| --------- | ---------: | --------: |
+| Insert    | 1,000 rows | ~25.64 ms |
+| Read      | 1,000 rows | ~10.96 ms |
+
+These measurements are useful as regression indicators for the driver implementation.
+
+They **must not** be interpreted as Google Sheets API production performance benchmarks.
+
+The test uses an in-memory fake client and therefore does not include network latency, Google API processing time, authentication, quotas, or real spreadsheet behavior.
+
+### Performance Testing
+
+Performance tests can be run independently from the normal test suite:
+
+```bash id="2q8n4x"
+bun test test/google-sheets/0007-performance.test.ts
+```
+
+The tests currently use a relatively loose regression threshold rather than guaranteeing a specific execution time.
+
+This is intentional because execution time can vary between development machines and CI environments.
+
+### When to Consider a Database
+
+Consider using a relational database instead when the workload requires:
+
+- large datasets
+- high-frequency reads and writes
+- complex queries
+- low-latency database operations
+- transactions
+- concurrent write-heavy workloads
+- database indexes and query planning
+
+Google Sheets is better suited when human spreadsheet access, simplicity, and integration with Google Workspace are important requirements.
+
+### Summary
+
+For better performance:
+
+1. Query only the data that is needed.
+2. Use filtering with `where`.
+3. Use deterministic sorting with pagination.
+4. Prefer batch operations for multiple records.
+5. Minimize unnecessary API requests.
+6. Use a custom client when application-specific caching or transport behavior is required.
+7. Use a relational database when the workload exceeds the practical characteristics of a spreadsheet.
+
+Performance should be evaluated using the application's actual workload rather than relying solely on the driver's local baseline tests.

package/docs/security.md

@@ -0,0 +1,153 @@
+## Security
+
+The Google Sheets driver requires access to a Google Cloud service account and a target spreadsheet.
+
+Security therefore depends on protecting both the authentication credentials and the spreadsheet itself.
+
+### Protect Service Account Credentials
+
+The default Google Sheets client requires:
+
+```ts
+credentials: {
+    clientEmail: '...',
+    privateKey: '...',
+}
+```
+
+The `privateKey` is sensitive and must be protected.
+
+Do not:
+
+- commit service account credentials to source control
+- expose the private key in client-side code
+- include credentials in public repositories
+- log the private key
+- send credentials to untrusted services
+
+Environment variables are recommended for local and server deployments:
+
+```env id="7k2p4m"
+GOOGLE_SHEETS_CLIENT_EMAIL=...
+GOOGLE_SHEETS_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n"
+```
+
+The application can then load these values when creating the data source.
+
+### Spreadsheet Access
+
+The service account must have access to the target spreadsheet.
+
+Access should follow the principle of least privilege:
+
+- grant access only to the spreadsheets required by the application
+- avoid sharing unrelated spreadsheets
+- remove access when the service account is no longer needed
+- review spreadsheet sharing permissions periodically
+
+The driver does not bypass Google Sheets permissions. Access is ultimately controlled by Google.
+
+### Spreadsheet ID
+
+The spreadsheet ID identifies the target spreadsheet:
+
+```ts id="3q8v1n"
+const dataSource = createGoogleSheetsDataSource({
+	type: "google-sheets",
+
+	spreadsheetId: process.env.GOOGLE_SHEETS_SPREADSHEET_ID!
+
+	// ...
+});
+```
+
+The spreadsheet ID is generally not considered a secret by itself.
+
+However, it should still be treated as application configuration because it identifies the resource the application intends to access.
+
+### Private Key Formatting
+
+When the private key is stored in an environment variable, escaped newline characters may need to be converted to actual newline characters:
+
+```ts id="6m4x9p"
+const privateKey = process.env.GOOGLE_SHEETS_PRIVATE_KEY!.replace(/\\n/g, "\n");
+```
+
+This should be done before passing the key to the Google authentication client when the deployment environment stores the key with escaped newlines.
+
+### Do Not Log Credentials
+
+Application logging should never include:
+
+```text id="1v7c5q"
+clientEmail
+privateKey
+access tokens
+authorization headers
+```
+
+If query or API logging is enabled for debugging, ensure that sensitive authentication information is not included in the logged output.
+
+### Custom Client Security
+
+A custom `GoogleSheetsClient` becomes part of the application's security boundary.
+
+For example, a custom client may implement:
+
+- authentication
+- caching
+- request logging
+- retry handling
+- alternative transports
+
+These implementations must follow the same security requirements as the default client.
+
+In particular, custom logging should not expose credentials or authorization data.
+
+### Production Credentials
+
+For production deployments:
+
+- store credentials in a secure secret-management system when available
+- restrict service-account permissions
+- rotate credentials according to the organization's security policy
+- avoid storing private keys directly in source code
+- restrict access to deployment configuration
+
+The exact secret-management mechanism depends on the deployment environment.
+
+### Synchronization Security
+
+`Synchronize` and `dropSchema` can modify worksheet structure.
+
+They should therefore be treated as privileged configuration in production.
+
+Do not enable destructive schema operations in production unless the application intentionally requires them and the consequences are understood.
+
+### Data Sensitivity
+
+The driver does not encrypt spreadsheet data at the application layer.
+
+If sensitive information is stored in Google Sheets, the application should consider:
+
+- who can access the spreadsheet
+- which service accounts have access
+- whether the data should be stored in a spreadsheet at all
+- whether additional application-level encryption is required
+
+Google Sheets should not automatically be considered an appropriate storage location for highly sensitive data.
+
+### Security Summary
+
+The main security responsibilities are:
+
+1. Protect the service account private key.
+2. Keep credentials out of source control.
+3. Restrict spreadsheet permissions.
+4. Avoid logging authentication information.
+5. Treat custom clients as part of the security boundary.
+6. Use secure secret storage in production.
+7. Be careful with `synchronize` and `dropSchema`.
+8. Evaluate whether sensitive data belongs in Google Sheets.
+
+The driver provides the integration layer, while authentication, authorization, credential management, and data classification remain application and infrastructure responsibilities.

package/docs/supported-features.md

@@ -0,0 +1,310 @@
+## Supported Features
+
+The Google Sheets driver supports a subset of TypeORM features that are applicable to Google Sheets.
+
+The following table summarizes the currently supported functionality.
+
+### Data Source
+
+| Feature                     | Status    |
+| --------------------------- | --------- |
+| Google Sheets data source   | Supported |
+| Custom Google Sheets client | Supported |
+| Multiple entities           | Supported |
+| Entity subscribers          | Supported |
+| Entity lifecycle hooks      | Supported |
+| Synchronization             | Supported |
+| Logging configuration       | Supported |
+
+### CRUD
+
+| Operation           | Status    |
+| ------------------- | --------- |
+| `insert()`          | Supported |
+| `save()`            | Supported |
+| `find()`            | Supported |
+| `findOne()`         | Supported |
+| `update()`          | Supported |
+| `delete()`          | Supported |
+| `remove()`          | Supported |
+| `softDelete()`      | Supported |
+| `restore()`         | Supported |
+| `softRemove()`      | Supported |
+| Multiple-row insert | Supported |
+| Multiple-row update | Supported |
+| Multiple-row delete | Supported |
+
+`save()` supports normal entity persistence and column-based foreign-key values.
+
+Nested relation persistence and cascade persistence are not fully supported. See [Limitations](#limitations) for details.
+
+### Find Options
+
+| Feature                         | Status    |
+| ------------------------------- | --------- |
+| `where`                         | Supported |
+| OR conditions using `where: []` | Supported |
+| `order`                         | Supported |
+| Multiple-field ordering         | Supported |
+| `skip`                          | Supported |
+| `take`                          | Supported |
+| `findAndCount()`                | Supported |
+| `count()`                       | Supported |
+| `findOne()` with `where`        | Supported |
+| `findOne()` with `order`        | Supported |
+| `withDeleted`                   | Supported |
+
+### Primary Keys
+
+| Feature                         | Status        |
+| ------------------------------- | ------------- |
+| `@PrimaryColumn()`              | Supported     |
+| `@PrimaryGeneratedColumn()`     | Supported     |
+| Increment generated IDs         | Supported     |
+| UUID generated IDs              | Supported     |
+| Explicit generated primary key  | Supported     |
+| Duplicate primary key detection | Supported     |
+| Missing primary key detection   | Supported     |
+| `identity` generation strategy  | Not supported |
+| `rowid` generation strategy     | Not supported |
+
+When an explicit generated primary key is supplied, the driver preserves the supplied value and checks for duplicates.
+
+### Data Types
+
+The driver uses TypeORM entity metadata to interpret worksheet values and hydrate them into the expected entity types.
+
+| Type      | Status    |
+| --------- | --------- |
+| `string`  | Supported |
+| `number`  | Supported |
+| `boolean` | Supported |
+| `Date`    | Supported |
+| `uuid`    | Supported |
+| `int`     | Supported |
+| `null`    | Supported |
+
+Google Sheets commonly returns cell values as strings. The driver performs type conversion based on the corresponding TypeORM column metadata.
+
+For example:
+
+```ts
+id: 1
+age: 30
+active: true
+createdAt: new Date(...)
+```
+
+are hydrated as their corresponding TypeScript runtime values rather than being returned as raw worksheet strings.
+
+### Entity Metadata
+
+| Feature                    | Status                                       |
+| -------------------------- | -------------------------------------------- |
+| Entity metadata resolution | Supported                                    |
+| Custom worksheet names     | Supported                                    |
+| Custom column names        | Supported                                    |
+| Naming strategies          | Supported through TypeORM-generated metadata |
+| Create date columns        | Supported                                    |
+| Update date columns        | Supported                                    |
+| Delete date columns        | Supported                                    |
+| Relation metadata          | Supported                                    |
+| Relation loading           | Supported                                    |
+
+### Relations
+
+Basic relation metadata, relation loading, and supported JOIN operations are supported.
+
+For example:
+
+```ts
+id: 1
+```
+
+```ts
+const post = await repository.findOne({
+	where: {
+		id: 1
+	},
+
+	relations: {
+		author: true
+	}
+});
+```
+
+Relations can also be represented through explicit foreign-key columns:
+
+```ts
+post.userId = user.id;
+
+await postRepository.save(post);
+```
+
+However, Google Sheets does not provide database-level relational features such as foreign-key constraints or referential integrity.
+
+Nested relation persistence and cascade operations are not fully supported.
+
+### Soft Delete
+
+Soft-delete operations using TypeORM delete-date metadata are supported.
+
+For example:
+
+```ts
+@DeleteDateColumn({
+    nullable: true,
+})
+deletedAt!: Date | null;
+```
+
+The driver supports:
+
+* `softDelete()`
+* `softRemove()`
+* `restore()`
+* filtering soft-deleted rows from normal queries
+* `withDeleted`
+* soft-delete filtering when loading supported relations
+
+Soft deletion remains an application-level operation because Google Sheets does not provide database-level soft-delete semantics.
+
+### Lifecycle Hooks
+
+The driver supports relevant TypeORM entity lifecycle hooks, including:
+
+```text
+@BeforeInsert
+@AfterInsert
+
+@BeforeUpdate
+@AfterUpdate
+
+@BeforeRemove
+@AfterRemove
+
+@AfterLoad
+```
+
+Entity subscribers are also supported.
+
+### Query Runner
+
+The driver provides a `QueryRunner` implementation for supported Google Sheets operations.
+
+Supported query operations include the operations implemented by the Google Sheets query interpreter and query runner.
+
+Unsupported operations are rejected by the driver rather than silently executed with potentially incorrect semantics.
+
+### Batch Operations
+
+The Google Sheets API client supports batching compatible operations to reduce the number of API requests.
+
+This includes:
+
+* multiple-row reads
+* multiple-row inserts
+* multiple-row updates
+* multiple-row deletes
+
+Non-contiguous updates may require separate API requests when the underlying ranges cannot be combined safely.
+
+### Transactions
+
+Database transactions are **not supported**.
+
+Google Sheets does not provide transactional semantics equivalent to a relational database.
+
+Applications should not rely on:
+
+```ts
+dataSource.transaction(...)
+```
+
+for atomic multi-operation behavior.
+
+See [Limitations](#limitations) for details.
+
+### Migrations
+
+Migration-related configuration is exposed through the data source options, but traditional relational database migrations are not supported as a full database migration mechanism.
+
+Schema changes should instead be handled through worksheet synchronization and the schema-management capabilities provided by the driver.
+
+### Synchronization
+
+Schema synchronization is supported for worksheet structures.
+
+The driver can:
+
+* create missing worksheets
+* create worksheet headers
+* add missing columns to existing worksheets
+
+Synchronization operates on worksheet structure rather than relational database schema objects.
+
+### Logging
+
+TypeORM logging configuration is supported.
+
+For example:
+
+```ts
+const dataSource = new DataSource({
+    type: 'google-sheets',
+
+    logging: [
+        'query',
+        'error',
+        'schema',
+    ],
+});
+```
+
+The driver integrates with TypeORM's logger for supported query, error, and schema operations.
+
+### Custom Client
+
+Applications can provide a custom `GoogleSheetsClient` implementation instead of using the default Google Sheets API client.
+
+This can be useful for:
+
+* testing
+* custom transport implementations
+* alternative data sources
+* controlling API behavior
+
+### Feature Compatibility Principle
+
+TypeORM exposes a large API surface because it supports many relational database systems.
+
+The presence of a TypeORM option does not automatically mean that the Google Sheets driver supports that option.
+
+Applications should rely on the capabilities documented by this driver and its tests rather than assuming full relational-database compatibility.
+
+### Summary
+
+The driver currently provides:
+
+```text
+TypeORM Repository
+        │
+        ├── CRUD
+        ├── Find Options
+        ├── Sorting
+        ├── Pagination
+        ├── Type Conversion
+        ├── Generated IDs
+        ├── Soft Delete
+        ├── Lifecycle Hooks
+        ├── Subscribers
+        ├── Relations / Relation Loading
+        ├── Synchronization
+        ├── Logging
+        └── Custom Client
+                │
+                ▼
+        Google Sheets
+```
+
+Features that depend on relational-database guarantees, such as transactions, foreign-key enforcement, database-level cascades, and full relational persistence semantics, are outside the capabilities of Google Sheets.