@d-osc/appscript-sheet-client

appscript-sheet-client

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

Install (from package folder):

npm install

Build:

npm run build

Two usage styles are supported:

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

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);

1. AppScriptClient (Mongo-like wrapper, recommended)

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):

// 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 จริง ตัวอย่างตรวจสอบ:

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)