appscript-sheet-client

TypeScript client for the Apps Script Google Sheets "Mongo-like" API implemented in this repo.

Install (from package folder):

``bash
npm install
`

Build:

`bash
npm run build
`

Two usage styles are supported:

1) Low-level AppScriptDatabase (direct mapping to API endpoints)

`ts
import { AppScriptDatabase } from './dist/index.js';

// Low level: call endpoints directly
const db = new AppScriptDatabase({ endpoint: 'https://script.google.com/macros/s/AK.../exec' });
await db.insertOne('users', { name: 'Alice' });
const results = await db.find('users', { name: 'Alice' });
console.log(results);
`

2) AppScriptClient (Mongo-like wrapper, recommended)

`ts
import { AppScriptClient } from './dist/index.js';

const client = new AppScriptClient('https://script.google.com/macros/s/AK.../exec');
await client.connect();
// Use a registered connection name (maps to ?db=NAME) or omit to use default
const db = client.db('prod');
const users = db.collection('users');

// Insert
await users.insertOne({ name: 'John', age: 25 });

// Find (returns cursor-like object with toArray())
const list = await users.find({}).toArray();
console.log(list);

// Bulk write
await users.bulkWrite([
{ insertOne: { document: { name: 'Bulk A' } } },
{ updateOne: { filter: { name: 'Bulk A' }, update: { age: 21 } } }
]);

await client.close();
`

Notes:
- The client keeps API parity with Mongo but operations are proxied to your Apps Script web app.
- db(name) maps to the ?db=name query parameter for selecting registered spreadsheet connections.
- connect() / close() are no-ops but included for compatibility.
- The server's update semantics are simple replacements (no $set/$inc operators yet).

Connection helpers (via the client):

`ts
// register a named spreadsheet connection (server script properties)
await client.client.addConnection('prod', 'SPREADSHEET_ID');
// list connections
await client.client.listConnections();
// remove
await client.client.removeConnection('prod');
`

Notes above apply: updates are simple replacements; you can request $set/$inc support if you prefer.

If you want, I can publish this package, add auth header support, or add operator support next.

ปัญหาและการแก้ไข (Edge cases & Troubleshooting)

ด้านล่างเป็นปัญหาที่พบบ่อยเมื่อเรียก Apps Script endpoint และวิธีจัดการเบื้องต้น (คำอธิบายเป็นภาษาไทย):

- Network / fetch errors
- อาการ: การเรียก fetch ล้มเหลว (timeout, DNS, network unreachable) หรือเกิด exception ก่อนได้ response.
- แนวทาง: ตรวจสอบการเชื่อมต่อ, URL ของ endpoint ถูกต้องหรือไม่, และลองเรียกด้วย curl/Postman เพื่อตรวจสอบผลลัพธ์จากภายนอกโค้ด

- Response ไม่ใช่ JSON / res.json() ล้มเหลว
- อาการ: res.json() โยน error เพราะ body ไม่ใช่ JSON หรือมีข้อความ error ในรูปแบบ text
- แนวทาง: ก่อนเรียก res.json() ให้ตรวจ res.ok / res.status และในกรณีผิดปกติให้อ่าน await res.text() เพื่อตรวจสอบ payload จริง ตัวอย่างตรวจสอบ:

`ts
const res = await fetch(url, opts);
if (!res.ok) {
const text = await res.text();
throw new Error(HTTP ${res.status}: ${text});
}
const data = await res.json();
`

- HTTP status (4xx / 5xx)
- อาการ: endpoint ตอบกลับ 400/401/403/500 และอาจมี JSON บอกสาเหตุ หรือเป็น HTML จาก Apps Script error
- แนวทาง: อ่าน res.status และ res.text() เพื่อสืบหา stack trace / message ที่ Apps Script ส่งกลับ ตรวจสอบการตั้งค่า permission ของ Apps Script (การแชร์/public access) ถ้าจำเป็นต้องใช้ auth ให้เพิ่ม header Authorization ใน fetch (หรือปรับ endpoint ให้รองรับ)

- CORS / Browser calls
- อาการ: เบราว์เซอร์บล็อกคำขอด้วย error เกี่ยวกับ CORS
- แนวทาง: ตรวจสอบการตั้งค่า Apps Script (ต้องเปิดเผย endpoint หรืออนุญาตต้นทางของคุณ) — สำหรับการพัฒนา อาจทดสอบด้วย curl/Node (ไม่ใช่เบราว์เซอร์) เพื่อแยกปัญหา

- ขนาด payload / Quotas ของ Apps Script
- อาการ: การส่ง insertMany หรือ bulkWrite ขนาดใหญ่ล้มเหลว, หรือ endpoint ตอบช้าจน timeout
- แนวทาง: แบ่งเป็น batch ย่อย ๆ, ตรวจสอบ quotas ของ Apps Script (payload size, execution time). สำหรับชุดข้อมูลขนาดใหญ่ ให้พิจารณาส่งข้อมูลเป็นหลายคำขอหรือใช้บริการที่รองรับ payload ขนาดใหญ่กว่า

- Query format / serialization
- อาการ: คำค้น (query q) ไม่ทำงานตามคาด เพราะรูปแบบ JSON แตกต่างจากที่ server คาดหวัง
- แนวทาง: ไลบรารีจะ JSON.stringify ค่า q เมื่อส่งผ่าน URL param ในบางเมทอด ให้ตรวจสอบกับฝั่ง server ว่ารับรูปแบบไหน (ตัวอย่าง: field ชื่อ _id ต้องเป็น string หรือ object)

- การดีบัก (debugging)
- ปริ้น await res.text() ถ้า res.json() ล้มเหลว เพื่อดู payload จริง
- ทดสอบ endpoint ด้วย curl/Postman ก่อนเรียกจากโค้ด
- เพิ่ม logging ใน Apps Script เพื่อดูว่าคำขอเข้ามาถึงหรือไม่ และตรวจสอบข้อผิดพลาดใน Executions (Google Apps Script dashboard)

ข้อเสนอแนะการปรับปรุงในโค้ด

- เพิ่มการตรวจสอบ res.ok ก่อนเรียก res.json() และโยน error ที่มีรายละเอียด (status + body)
- ให้ opsi สำหรับส่ง custom headers (เช่น Authorization) ผ่าน AppScriptDatabase` หรือ constructor options
- เพิ่ม retry/backoff สำหรับคำขอที่ล้มเหลวแบบชั่วคราว (HTTP 429/5xx)