tantan-typeorm-gs 1.0.0

package/docs/limitations.md

@@ -0,0 +1,223 @@
+## Limitations
+
+The Google Sheets driver provides a TypeORM-compatible interface, but Google Sheets is not a relational database.
+
+As a result, some TypeORM features cannot provide the same guarantees as a traditional database such as PostgreSQL or MySQL.
+
+### No Transactional Guarantees
+
+Transactions are not supported.
+
+Operations involving multiple writes cannot be treated as one atomic database transaction.
+
+For example:
+
+```ts
+await repository.save(user);
+await repository.save(profile);
+```
+
+If the second operation fails, the first operation is not automatically rolled back.
+
+Applications that require atomic multi-step updates should use a transactional database instead.
+
+### No Foreign Key Enforcement
+
+Relations can be defined and loaded:
+
+```ts
+@ManyToOne(
+    () => User,
+    {
+        nullable: false,
+    },
+)
+author!: User;
+```
+
+However, Google Sheets does not enforce foreign-key constraints.
+
+The driver therefore cannot guarantee that a relation always points to an existing row.
+
+For example, a row may contain:
+
+```text
+authorId = 999
+```
+
+even when no corresponding user exists.
+
+Applications are responsible for maintaining referential integrity.
+
+### No Database-Level Cascades
+
+Database-level cascading behavior is not available.
+
+Operations such as deleting a parent row do not automatically provide the same cascading guarantees as a relational database.
+
+If related rows must also be modified or deleted, the application must explicitly perform those operations.
+
+### Limited Relation Persistence
+
+Relation metadata and relation loading are supported, but relation persistence does not provide the full behavior of a relational database or TypeORM cascade system.
+
+For example, explicitly assigning a foreign-key column is supported:
+
+```ts
+post.userId = user.id;
+
+await postRepository.save(post);
+```
+
+However, nested relation persistence and cascade operations are not fully supported.
+
+For example, applications should not rely on behavior such as:
+
+```ts
+await userRepository.save({
+    name: 'Budi',
+    posts: [
+        {
+            title: 'Post 1',
+        },
+    ],
+});
+```
+
+when this requires TypeORM to automatically persist related entities.
+
+Applications should explicitly persist related entities when necessary.
+
+### Spreadsheet-Based Performance
+
+Google Sheets is designed as a spreadsheet and API-based data store, not as a high-performance database engine.
+
+Operations over large datasets can become increasingly expensive because rows must be retrieved and processed through the driver.
+
+For example, operations such as:
+
+```ts
+await repository.find();
+```
+
+may require processing a large number of worksheet rows.
+
+Applications should therefore avoid treating a large spreadsheet as a replacement for a database.
+
+### Offset-Based Pagination
+
+Pagination uses `skip` and `take`.
+
+```ts
+await repository.find({
+    skip: 100,
+    take: 20
+});
+```
+
+This provides offset-based pagination rather than database-style indexed or cursor-based pagination.
+
+For large worksheets, deep offsets may require processing a substantial amount of data before the requested page can be returned.
+
+### Limited Query Semantics
+
+The driver supports the query operations implemented by its query interpreter and query runner.
+
+It does not provide every SQL feature available in a relational database.
+
+Applications should not assume that arbitrary SQL syntax supported by PostgreSQL, MySQL, or another database will work with Google Sheets.
+
+Unsupported operations are rejected rather than silently interpreted as equivalent operations.
+
+### Concurrent Updates
+
+Google Sheets does not provide the same concurrency guarantees as a transactional database.
+
+When multiple applications or users modify the same worksheet concurrently, applications should consider the possibility of conflicting updates.
+
+The driver should therefore not be used for workloads that require strong database-level concurrency control.
+
+### Primary Key Limitations
+
+Generated primary keys are supported for the strategies implemented by the driver.
+
+Currently:
+
+| Generation strategy | Status        |
+| ------------------- | ------------- |
+| `increment`         | Supported     |
+| `uuid`              | Supported     |
+| `identity`          | Not supported |
+| `rowid`             | Not supported |
+
+For manually defined primary keys using `@PrimaryColumn()`, the application must provide a value.
+
+Duplicate generated primary keys are rejected by the driver.
+
+### Schema Management Limitations
+
+Synchronization operates on worksheet structures rather than a relational database schema.
+
+There are no traditional database objects such as:
+
+* indexes with database query-planning semantics
+* foreign-key constraints
+* transactional schema changes
+* database-enforced unique constraints
+
+`dropSchema` and `synchronize` should therefore be used carefully, particularly when the spreadsheet contains data that must be preserved.
+
+### Relations Are Not Relational Database Guarantees
+
+Relation metadata and relation loading are supported, but this should not be interpreted as full relational-database support.
+
+The following remain application-level responsibilities:
+
+* referential integrity
+* cascade behavior
+* transactional relation updates
+* consistency across related worksheets
+
+### API Dependency
+
+The default client communicates with Google Sheets through the Google Sheets API.
+
+Therefore, applications using the default client depend on:
+
+* Google Cloud configuration
+* valid authentication credentials
+* spreadsheet permissions
+* Google API availability
+* API quotas and limits
+
+A custom client can be used when the application needs different transport or testing behavior.
+
+### When Not to Use This Driver
+
+A relational database is generally more appropriate when the application requires:
+
+* transactions
+* strong consistency guarantees
+* foreign-key enforcement
+* complex relational queries
+* large-scale datasets
+* high-frequency concurrent writes
+* database-level indexing and query optimization
+
+The Google Sheets driver is better suited to workloads where spreadsheet accessibility and TypeORM integration are more important than full relational-database capabilities.
+
+### Summary
+
+The main limitation is architectural:
+
+```text
+TypeORM API
+     ↓
+Google Sheets Driver
+     ↓
+Spreadsheet
+```
+
+The TypeORM API provides a familiar programming model, but it cannot add database capabilities that Google Sheets itself does not provide.
+
+The driver should therefore be considered a **TypeORM interface for Google Sheets**, not a replacement for a relational database.

package/docs/pagination.md

@@ -0,0 +1,384 @@
+## Pagination
+
+Pagination can be implemented using TypeORM's `skip` and `take` find options.
+
+The Google Sheets driver supports this offset-based pagination pattern.
+
+### Basic Pagination
+
+Define the page number and page size:
+
+```ts id="8j3p7k"
+const page = 1;
+const pageSize = 20;
+
+const users = await repository.find({
+	skip: (page - 1) * pageSize,
+	take: pageSize
+});
+```
+
+For example:
+
+| Page | Page size | Skip | Take |
+| ---: | --------: | ---: | ---: |
+|    1 |        20 |    0 |   20 |
+|    2 |        20 |   20 |   20 |
+|    3 |        20 |   40 |   20 |
+
+The formula is:
+
+```text id="wqk5j1"
+skip = (page - 1) * pageSize
+```
+
+### Pagination with Sorting
+
+Pagination should generally be combined with a deterministic ordering:
+
+```ts id="6xj2pz"
+const page = 2;
+const pageSize = 20;
+
+const users = await repository.find({
+	order: {
+		id: "ASC"
+	},
+
+	skip: (page - 1) * pageSize,
+
+	take: pageSize
+});
+```
+
+Using `order` makes the result ordering explicit before applying the offset and limit.
+
+### Pagination with Filtering
+
+Pagination can also be combined with `where`:
+
+```ts id="h9k4s2"
+const page = 1;
+const pageSize = 20;
+
+const users = await repository.find({
+	where: {
+		name: "Budi"
+	},
+
+	order: {
+		id: "ASC"
+	},
+
+	skip: (page - 1) * pageSize,
+
+	take: pageSize
+});
+```
+
+The filtering is applied before the pagination window is returned.
+
+### Pagination with Total Count
+
+When the application needs both the current page and the total number of matching records, use `findAndCount()`:
+
+```ts id="4w8m1r"
+const page = 1;
+const pageSize = 20;
+
+const [users, total] = await repository.findAndCount({
+	where: {
+		name: "Budi"
+	},
+
+	order: {
+		id: "ASC"
+	},
+
+	skip: (page - 1) * pageSize,
+
+	take: pageSize
+});
+```
+
+`users` contains the entities for the requested page, while `total` contains the total number of matching entities.
+
+For example:
+
+```ts id="5h2d8q"
+const totalPages = Math.ceil(total / pageSize);
+```
+
+The application can then expose pagination information:
+
+```ts id="p6c1vx"
+{
+    data: users,
+    page,
+    pageSize,
+    total,
+    totalPages,
+}
+```
+
+### Reusable Pagination Helper
+
+A helper function can be used to keep pagination logic consistent:
+
+```ts id="9m4z7a"
+async function findPage(page: number, pageSize: number) {
+	const [data, total] = await repository.findAndCount({
+		order: {
+			id: "ASC"
+		},
+
+		skip: (page - 1) * pageSize,
+
+		take: pageSize
+	});
+
+	return {
+		data,
+		page,
+		pageSize,
+		total,
+		totalPages: Math.ceil(total / pageSize)
+	};
+}
+```
+
+Usage:
+
+```ts id="2c8v1n"
+const result = await findPage(2, 20);
+
+console.log(result.data);
+console.log(result.total);
+console.log(result.totalPages);
+```
+
+### Pagination Considerations
+
+Pagination through `skip` and `take` is offset-based.
+
+For large worksheets, increasing the offset means the driver still needs to process the preceding rows before returning the requested page. Therefore, pagination is convenient for normal application-level data sets but should not be treated as equivalent to database indexing or cursor-based pagination.
+
+For large-scale data, consider whether Google Sheets is appropriate as the primary data store and evaluate the performance characteristics of the target spreadsheet.
+
+### Summary
+
+The basic pagination pattern is:
+
+```text id="6v3yqk"
+page
+  ↓
+(page - 1) × pageSize
+  ↓
+skip
+  ↓
+take pageSize
+  ↓
+current page
+```
+
+For applications that need the total number of records, prefer:
+
+```ts id="8n2w6c"
+repository.findAndCount({
+	skip,
+	take
+});
+```
+
+This provides both the current page and the total matching record count.
+
+## Sorting
+
+Sorting is performed using TypeORM's `order` find option.
+
+The Google Sheets driver supports sorting by one or more entity properties.
+
+### Sort Ascending
+
+To sort a result in ascending order:
+
+```ts id="6p2r8m"
+const users = await repository.find({
+	order: {
+		name: "ASC"
+	}
+});
+```
+
+For example, names are returned alphabetically:
+
+```text id="5k1d9v"
+Andi
+Budi
+Citra
+Siti
+```
+
+### Sort Descending
+
+Use `DESC` for descending order:
+
+```ts id="1x7m4q"
+const users = await repository.find({
+	order: {
+		name: "DESC"
+	}
+});
+```
+
+The result is returned in reverse ordering.
+
+### Multiple Sort Fields
+
+Multiple properties can be specified:
+
+```ts id="8q4n2s"
+const users = await repository.find({
+	order: {
+		name: "ASC",
+		email: "DESC"
+	}
+});
+```
+
+The first field is used as the primary sort key.
+
+The next field is used when rows have the same value for the preceding field.
+
+Conceptually:
+
+```text
+name ASC
+    ↓
+email DESC
+```
+
+### Sorting with Filtering
+
+Sorting can be combined with `where`:
+
+```ts id="3c7w9k"
+const users = await repository.find({
+	where: {
+		name: "Budi"
+	},
+
+	order: {
+		email: "ASC"
+	}
+});
+```
+
+Only matching rows are returned, ordered by `email`.
+
+### Sorting with Pagination
+
+For pagination, sorting should normally be specified explicitly:
+
+```ts id="0v5m2x"
+const page = 2;
+const pageSize = 20;
+
+const users = await repository.find({
+	order: {
+		id: "ASC"
+	},
+
+	skip: (page - 1) * pageSize,
+
+	take: pageSize
+});
+```
+
+Using a deterministic sort order makes the pagination result predictable.
+
+### Sorting with Find One
+
+`findOne()` can also use `order`:
+
+```ts id="7r1k6p"
+const user = await repository.findOne({
+	order: {
+		id: "ASC"
+	}
+});
+```
+
+This is useful when a condition may match multiple rows but the application needs a deterministic first result.
+
+### Entity Property Names
+
+The `order` option uses entity property names:
+
+```ts id="2d8x5m"
+@Entity("users")
+class User {
+	@PrimaryGeneratedColumn()
+	id!: number;
+
+	@Column()
+	displayName!: string;
+}
+```
+
+The repository query uses:
+
+```ts id="9q3h7v"
+await repository.find({
+	order: {
+		displayName: "ASC"
+	}
+});
+```
+
+If a custom database/worksheet column name is configured, the application still works with the entity property:
+
+```ts id="4m6z1c"
+@Column({
+    name: 'display_name',
+})
+displayName!: string;
+```
+
+Query:
+
+```ts id="1s8k4w"
+await repository.find({
+	order: {
+		displayName: "ASC"
+	}
+});
+```
+
+TypeORM metadata resolves the entity property to the corresponding worksheet column.
+
+### Summary
+
+The basic sorting syntax is:
+
+```ts id="5n2q8b"
+await repository.find({
+	order: {
+		propertyName: "ASC"
+	}
+});
+```
+
+or:
+
+```ts id="7c4m1x"
+await repository.find({
+	order: {
+		propertyName: "DESC"
+	}
+});
+```
+
+Multiple fields can be combined when a secondary ordering is required.
+
+Sorting is especially useful together with `skip` and `take` for predictable pagination.