npm package discovery and stats viewer.

Discover Tips

  • General search

    [free text search, go nuts!]

  • Package details

    pkg:[package-name]

  • User packages

    @[username]

Sponsor

Optimize Toolset

I’ve always been into building performant and accessible sites, but lately I’ve been taking it extremely seriously. So much so that I’ve been building a tool to help me optimize and monitor the sites that I build to make sure that I’m making an attempt to offer the best experience to those who visit them. If you’re into performant, accessible and SEO friendly sites, you might like it too! You can check it out at Optimize Toolset.

About

Hi, 👋, I’m Ryan Hefner  and I built this site for me, and you! The goal of this site was to provide an easy way for me to check the stats on my npm packages, both for prioritizing issues and updates, and to give me a little kick in the pants to keep up on stuff.

As I was building it, I realized that I was actually using the tool to build the tool, and figured I might as well put this out there and hopefully others will find it to be a fast and useful way to search and browse npm packages as I have.

If you’re interested in other things I’m working on, follow me on Twitter or check out the open source projects I’ve been publishing on GitHub.

I am also working on a Twitter bot for this site to tweet the most popular, newest, random packages from npm. Please follow that account now and it will start sending out packages soon–ish.

Open Software & Tools

This site wouldn’t be possible without the immense generosity and tireless efforts from the people who make contributions to the world and share their work via open source initiatives. Thank you 🙏

© 2026 – Pkg Stats / Ryan Hefner

@d-zero/google-sheets

v0.13.1

Published

Google Sheets API Toolkit

Readme

@d-zero/google-sheets

Google Sheets API を型安全にラップしたライブラリ。SheetTableで「ヘッダー定義済みのテーブル」として読み書きする。

Installation

yarn add @d-zero/google-sheets @d-zero/google-auth

Usage

import { authentication } from '@d-zero/google-auth';
import { SheetTable } from '@d-zero/google-sheets';

const auth = await authentication(null, ['https://www.googleapis.com/auth/spreadsheets']);

const table = await SheetTable.create(
	'https://docs.google.com/spreadsheets/d/YOUR_SPREADSHEET_ID/edit',
	'Users',
	auth,
	{
		define: {
			name: '名前',
			email: 'メールアドレス',
			age: '年齢',
			registered: '登録日',
		},
	},
);

await table.addRecords([
	{ name: '田中太郎', email: '[email protected]', age: { value: 25 } },
]);

Drive フォルダ URL から新規作成

createSpreadsheetは Drive フォルダ URL を受け取り、そのフォルダ内にスプレッドシートを新規作成する。parseGoogleUrlで URL 種別を判別すれば、「フォルダ URL なら新規作成、スプレッドシート URL なら既存に書き込み」と分岐できる。フォルダ URL はhttps://drive.google.com/drive/folders/<id>形式のみ受理する(open?id=はフォルダとファイルを URL から区別できないため非対応)。

import { authentication } from '@d-zero/google-auth';
import { createSpreadsheet, parseGoogleUrl, Sheets } from '@d-zero/google-sheets';

// Drive scope が必要(spreadsheets scope だけではフォルダに配置できない)
const auth = await authentication(null, [
	'https://www.googleapis.com/auth/spreadsheets',
	'https://www.googleapis.com/auth/drive.file',
]);

const target = parseGoogleUrl(input);
const sheetUrl =
	target?.kind === 'drive-folder'
		? (await createSpreadsheet(input, '集計結果', auth)).url
		: input;

const sheets = new Sheets(sheetUrl, auth);

シートの構造操作

Sheets.createで得たSheetに対して、名前変更・保護・削除・並び替え・非表示ができる。再表示(unhide)と保護解除(unprotect)の API は提供しない。

const sheet = await sheets.create('集計');

await sheet.rename('集計 v2');
await sheet.move(0);
await sheet.hide();

// editors を渡す(推奨)
await sheet.protect({
	editors: ['[email protected]', '[email protected]'],
	description: '自動生成の集計シート',
});

await sheet.delete();

protectのeditors(期待とずれやすい)

  • 省略または空配列にすると、シートを編集できるのはスプレッドシートの所有者だけになる。ファイルの編集権限があってもシートは編集できない
  • 実行者が所有者でないのに自分のメールを入れ忘れると、自分も編集できなくなる
  • セルを編集できる人と、UI の「シートと範囲を保護」からその保護を変更・削除できる人は同じ集合。所有者は常に両方できる。「誰もセルを触れない」と「ファイル編集者の誰でも解除できる」は分けられない
  • セキュリティ境界ではない。印刷・コピー・貼り付け・書き出しで内容は持ち出せる。ブックのコピーにこの保護は残らない
  • warningOnly: trueは確認ダイアログだけで誰でも編集できる。ダイアログの文言は固定で、任意の文は定義できない。このときeditorsは送らない
  • descriptionは右パネル「シートと範囲を保護」の見出しになるだけ。権限とダイアログ本文は変わらない
  • 対象はセルの値だけではない。書式だけをロックして値の入力は許す分け方はできない。全員に見えるフィルタは、保護された範囲にかかると作成・変更できない。自分だけのフィルタ表示は作れる

書式・条件付き書式・読み取り API はsrc/sheet-table.tsの JSDoc を参照。

重要な制約

  • 大量行のストリーミング送信は 2500 行チャンクで自動分割される(Sheets API のメモリ・タイムアウト制約への対応)
  • 遅延セル({ value: thunk })は flush 中に自動展開される。展開中に新たな遅延セルが見つかった場合は早期 flush を停止して整合性を保つ
  • onProgressコールバック内でaddRecordsを再入呼びしてはならない — buffer mutation 破壊で行順が壊れる
  • createSpreadsheetはリトライしない・同名ファイルを検索しない — files.createは非冪等で、リトライすると二重作成し得るため。呼ぶたびに新規作成する
  • 同一インスタンスへの並列呼び出し禁止 — 行順・送信件数の保証は逐次呼び出し前提

理由・実装はsrc/sheet-table.tsおよびsrc/sheet.tsの JSDoc を参照。