Javascript SDK (Browser + Node JS)
Overview
Sheet2DB is a TypeScript class that provides an easy interface to interact with Google Sheets via the sheet2db (opens in a new tab) API. This class abstracts the complexity of API calls and provides a simple way to read, write, update, and delete data in Google Sheets. It supports both browser and Node.js environments.
Installation
npm install @sheet2db/sdkConfiguration Options
Sheet2DBOptions
- mode:
'apikey' | 'connectionId'- Authentication mode. - apiKey:
string(required for'apikey'mode) - API key for accessing the spreadsheet. - spreadsheetId:
string(required for'apikey'mode) - The ID of the Google spreadsheet. - version:
"v1"- API version, always "v1". - connectionId:
string(required for'connectionId'mode) - Connection ID for accessing the spreadsheet. - basicAuth:
{ username: string; password: string; }(optional for'connectionId'mode) - Basic authentication credentials. - jwtAuth:
{ bearerToken: string; }(optional for'connectionId'mode) - JWT authentication token. - fetchFn:
typeof fetch(optional) - Custom fetch function.
Usage
Import and Initialize
import { Sheet2DB,Sheet2DBOptions } from '@sheet2db/sdk';
const options: Sheet2DBOptions = {
mode: 'apikey',
apiKey: 'your-api-key',
spreadsheetId: 'your-spreadsheet-id',
version: 'v1'
};
const options: Sheet2DBOptions = {
mode: 'connectionId',
connectionId: 'your-connection-id',
version: 'v1'
};
const sheet2db = new Sheet2DB(options);Methods
ReadContent
Fetches content from the spreadsheet.
Parameters
- limit (optional):
number- Maximum number of records to return. - offset (optional):
number- Number of records to skip before starting to return records. - sheet (optional):
string- The name of the sheet to read from. - format (optional):
'records' | 'dict' | 'series' | 'split' | 'index' | 'raw'- The format of the returned data. - cast_numbers (optional):
string- Cast numbers to specified type. - value_render (optional):
'FORMATTED_VALUE' | 'UNFORMATTED_VALUE' | 'FORMULA'- The value render option.
Example
sheet2db.ReadContent({ sheet: 'Sheet1', limit: 10 })
.then(data => console.log(data))
.catch(error => console.error(error));Keys
Gets the keys of the spreadsheet.
Parameters
- sheet (optional):
string- The name of the sheet to get keys from.
Example
sheet2db.Keys({ sheet: 'Sheet1' })
.then(keys => console.log(keys))
.catch(error => console.error(error));Count
Gets the count of rows in the spreadsheet.
Parameters
- sheet (optional):
string- The name of the sheet to count rows in.
Example
sheet2db.Count({ sheet: 'Sheet1' })
.then(count => console.log(count))
.catch(error => console.error(error));Title
Gets the title of the spreadsheet.
Example
sheet2db.Title()
.then(title => console.log(title))
.catch(error => console.error(error));Range
Gets a range of values from the spreadsheet.
Parameters
- range:
string- The range to fetch, in A1 notation.
Example
sheet2db.Range({ range: 'A1:B2' })
.then(range => console.log(range))
.catch(error => console.error(error));Search
Searches for records in the spreadsheet.
Parameters
- sheet (optional):
string- The name of the sheet to search in. - or (optional):
boolean- If true, uses OR logic for the search. - query:
string- The search query.
Example
sheet2db.Search({ query: 'name=John', sheet: 'Sheet1' })
.then(records => console.log(records))
.catch(error => console.error(error));Insert
Inserts data into the spreadsheet.
Parameters
- data:
Record<string, any> | Record<string, any>[]- The data to insert. - sheet (optional):
string- The name of the sheet to insert data into.
Example
sheet2db.Insert({ data: { name: 'John', age: 30 }, sheet: 'Sheet1' })
.then(response => console.log(response))
.catch(error => console.error(error));UpdateRow
Updates a specific row in the spreadsheet.
Parameters
- row:
number- The row number to update. - data:
Record<string, any>- The data to update. - sheet (optional):
string- The name of the sheet to update data in.
Example
sheet2db.UpdateRow({ row: 1, data: { age: 31 }, sheet: 'Sheet1' })
.then(response => console.log(response))
.catch(error => console.error(error));UpdateWithQuery
Updates rows based on a query.
Parameters
- sheet (optional):
string- The name of the sheet to update data in. - query:
string- The query to identify rows to update. - data:
Record<string, any>- The data to update.
Example
sheet2db.UpdateWithQuery({ query: 'name=John', data: { age: 32 }, sheet: 'Sheet1' })
.then(response => console.log(response))
.catch(error => console.error(error));BatchUpdate
Updates multiple records in batches.
Parameters
- sheet (optional):
string- The name of the sheet to update data in. - batches:
{ query: string, record: Record<string, any> }[]- The batch update data.
Example
sheet2db.BatchUpdate({ batches: [{ query: 'name=John', record: { age: 33 } }], sheet: 'Sheet1' })
.then(response => console.log(response))
.catch(error => console.error(error));DeleteRow
Deletes a specific row in the spreadsheet.
Parameters
- row:
number- The row number to delete. - sheet (optional):
string- The name of the sheet to delete the row from.
Example
sheet2db.DeleteRow({ row: 1, sheet: 'Sheet1' })
.then(response => console.log(response))
.catch(error => console.error(error));DeleteWithQuery
Deletes rows based on a query.
Parameters
- query:
string- The query to identify rows to delete. - sheet (optional):
string- The name of the sheet to delete rows from.
Example
sheet2db.DeleteWithQuery({ query: 'name=John', sheet: 'Sheet1' })
.then(response => console.log(response))
.catch(error => console.error(error));Clear
Clears all data from a sheet.
Parameters
- sheet:
string- The name of the sheet to clear.
Example
sheet2db.Clear({ sheet: 'Sheet1' })
.then(response => console.log(response))
.catch(error => console.error(error));CreateSheet
Creates a new sheet in the spreadsheet.
Parameters
- title (optional):
string- The title of the new sheet.
Example
sheet2db.CreateSheet({ title: 'NewSheet' })
.then(response => console.log(response))
.catch(error => console.error(error));DeleteSheet
Deletes a sheet from the spreadsheet.
Parameters
- sheet:
string- The name of the sheet to delete.
Example
sheet2db.DeleteSheet({ sheet: 'Sheet1' })
.then(response => console.log(response))
.catch(error => console.error(error));Environment Detection
The library automatically detects the environment (browser or Node.js) and uses the appropriate fetch implementation.
let fetchFunction: typeof fetch;
if (typeof window !== 'undefined' && typeof window.fetch !== 'undefined') {
fetchFunction = window.fetch.bind(window);
} else {
fetchFunction = async (...args) => {
const fetch = global.fetch;
return fetch(...args);
};
}Error Handling
Each method returns a promise that resolves to the API response or rejects with an error.
sheet2db.ReadContent()
.then(data => console.log(data))
.catch(error => console.error(error));