@ciderjs/gasnuki

Type definitions and utilities for Google Apps Script client-side API

Overview

gasnuki provides TypeScript type definitions and utilities for safely using the Google Apps Script client-side API. It helps ensure type-safe communication between Apps Script and your frontend.

Installation

npm install @ciderjs/gasnuki

pnpm add @ciderjs/gasnuki

Usage

Generate type definitions by running:

npx @ciderjs/gasnuki

... or, add project's npm-script in package.json:

{
  // others...
  "scripts": {
    "gas": "gasnuki"
  }
}

This will generate type definition files in the types directory by default.

Vite Plugin Usage

If you are using Vite, you can integrate gasnuki as a plugin to automatically generate types when your server-side files change.

Install vite and @ciderjs/gasnuki:
```
pnpm add -D vite @ciderjs/gasnuki
```

Add the plugin to your vite.config.ts:

import { defineConfig } from 'vite';
import { gasnuki } from '@ciderjs/gasnuki/vite';

export default defineConfig({
  plugins: [
    gasnuki({
      /* options */
    }),
  ],
});

Now, when you run vite dev, gasnuki will automatically watch for changes in your Apps Script source files and regenerate the types.

Make sure the generated directory (default: types) is included in your tsconfig.json:

{
  "compilerOptions": {
    // ... your options ...
  },
  "include": [
    "src",
    "types" // Add this line if your type definitions are in the 'types' directory
  ]
}

Then, you can use google with Type Definitions.

// Type-safe access to google.script.run
// Example: Call the server-side function getContent

google.script.run
  .withSuccessHandler((result) => {
    console.log(result);
  })
  .getContent('Sheet1');

Features

Type definitions for Google Apps Script client-side API
Utility type to convert server-side function return types to void

Promise-based Wrapper

For a more modern asynchronous approach, you can use the type-safe Promise-based wrapper for google.script.run. This allows you to write clean code with async/await.

First, import the type definitions (ServerScripts) generated by gasnuki and the getPromisedServerScripts function.

import { getPromisedServerScripts } from '@ciderjs/gasnuki/promise';
// Specify the path to the type definitions generated by gasnuki
import type { ServerScripts } from '../types/appsscript';

export const gas = getPromisedServerScripts<ServerScripts>();

Use the created gas object to call your server-side functions with async/await.

import { gas } from '../lib/gas';

async function fetchData() {
  try {
    // The arguments and return value of 'getContent' are now type-safe!
    const result = await gas.getContent('Sheet1');
    console.log(result);
  } catch (error) {
    console.error(error);
  }
}

Development with Mockups

By passing mockup functions to getPromisedServerScripts, you can proceed with frontend development without needing to clasp push every time.

import {
  getPromisedServerScripts,
  type PartialScriptType,
} from '@ciderjs/gasnuki/promise';
import type { ServerScripts } from '../types/appsscript';

// Define mockup functions for development
const mockup: PartialScriptType<ServerScripts> = {
  // Simulate the behavior of the sayHello function
  sayHello: async (name) => {
    await new Promise(resolve => setTimeout(resolve, 500)); // Simulate network delay
    return `Hello from mockup, ${name}!`;
  },
  // Other functions can be mocked similarly
};

export const gas = getPromisedServerScripts<ServerScripts>(mockup);

Contributing

Bug reports and pull requests are welcome. Please use the issues or pull requests section.

License

MIT