@ciderjs/gasnuki 0.4.1 → 0.5.0

package/README.ja.md

@@ -1,9 +1,10 @@
 # @ciderjs/gasnuki
 
 [![README-en](https://img.shields.io/badge/English-blue?logo=ReadMe)](./README.md)
-[![Test Coverage](https://img.shields.io/badge/test%20coverage-93.02%25-brightgreen)](https://github.com/luthpg/gasnuki)
+[![Test Coverage](https://img.shields.io/badge/test%20coverage-93.03%25-brightgreen)](https://github.com/luthpg/gasnuki)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![npm version](https://img.shields.io/npm/v/@ciderjs/gasnuki.svg)](https://www.npmjs.com/package/@ciderjs/gasnuki)
+![NPM Downloads](https://img.shields.io/npm/dw/@ciderjs/gasnuki)
 [![GitHub issues](https://img.shields.io/github/issues/luthpg/gasnuki.svg)](https://github.com/luthpg/gasnuki/issues)
 
 Google Apps Script クライアントサイドAPIの型定義・ユーティリティ
@@ -160,7 +161,7 @@ import {
 import type { ServerScripts } from '../types/appsscript';
 
 // 開発用のモック関数を定義します
-const mockup: PartialScriptType<ServerScripts> = {
+const mockupFunctions: PartialScriptType<ServerScripts> = {
   // sayHello関数の動作をシミュレート
   sayHello: async (name) => {
     await new Promise(resolve => setTimeout(resolve, 500)); // ネットワーク遅延を模倣
@@ -169,7 +170,33 @@ const mockup: PartialScriptType<ServerScripts> = {
   // 他の関数も同様にモックできます
 };
 
-export const gas = getPromisedServerScripts<ServerScripts>(mockup);
+export const gas = getPromisedServerScripts<ServerScripts>({ mockupFunctions });
+```
+
+### 型安全な JSON パース (Optional)
+
+通常、Google Apps Script とクライアント間の通信で `JSON.parse()` を使うと戻り値が `any` になってしまいます。また、`Date` 型などはシリアライズの過程で文字列に変換され、手動での復元が必要になります。
+
+`gasnuki` は、シリアライズ前の型情報を Branded Type (`JsonString<T>`) として保持することで、**`any` を介さない型安全な復元**を可能にします。
+
+`getPromisedServerScripts` のオプションに `{ parseJson: true }` を指定すると、サーバー側で `serialize()` された戻り値を自動でデシリアライズし、`Date` オブジェクトも正しく復元します。
+
+```ts
+// サーバー側 (Apps Script)
+// const getAppData = () => serialize({ updatedAt: new Date(), user: 'Alice' });
+
+// クライアント側
+export const gas = getPromisedServerScripts<ServerScripts>({
+  parseJson: true
+});
+
+async function fetchData() {
+  // 戻り値は `any` ではなく、元のオブジェクト型として推論されます
+  // Date オブジェクトも自動的に復元されます
+  const result = await gas.getAppData();
+  console.log(result.user); // 'Alice' (string)
+  console.log(result.updatedAt instanceof Date); // true
+}
 ```
 
 ## コントリビュート

package/README.md

@@ -1,9 +1,10 @@
 # @ciderjs/gasnuki
 
 [![README-ja](https://img.shields.io/badge/日本語-blue?logo=ReadMe)](./README.ja.md)
-[![Test Coverage](https://img.shields.io/badge/test%20coverage-93.02%25-brightgreen)](https://github.com/luthpg/gasnuki)
+[![Test Coverage](https://img.shields.io/badge/test%20coverage-93.03%25-brightgreen)](https://github.com/luthpg/gasnuki)
 [![License](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![npm version](https://img.shields.io/npm/v/@ciderjs/gasnuki.svg)](https://www.npmjs.com/package/@ciderjs/gasnuki)
+![NPM Downloads](https://img.shields.io/npm/dw/@ciderjs/gasnuki)
 [![GitHub issues](https://img.shields.io/github/issues/luthpg/gasnuki.svg)](https://github.com/luthpg/gasnuki/issues)
 
 Type definitions and utilities for Google Apps Script client-side API
@@ -160,7 +161,7 @@ import {
 import type { ServerScripts } from '../types/appsscript';
 
 // Define mockup functions for development
-const mockup: PartialScriptType<ServerScripts> = {
+const mockupFunctions: PartialScriptType<ServerScripts> = {
   // Simulate the behavior of the sayHello function
   sayHello: async (name) => {
     await new Promise(resolve => setTimeout(resolve, 500)); // Simulate network delay
@@ -169,7 +170,33 @@ const mockup: PartialScriptType<ServerScripts> = {
   // Other functions can be mocked similarly
 };
 
-export const gas = getPromisedServerScripts<ServerScripts>(mockup);
+export const gas = getPromisedServerScripts<ServerScripts>({ mockupFunctions });
+```
+
+### Type-Safe JSON Parsing (Optional)
+
+Normally, using `JSON.parse()` for communication between Google Apps Script and the client results in an `any` return type. Additionally, types like `Date` are converted to strings during serialization and require manual restoration.
+
+`gasnuki` preserves the original type information as a Branded Type (`JsonString<T>`), enabling **type-safe restoration without using `any`**.
+
+By passing `{ parseJson: true }` as the second argument to `getPromisedServerScripts`, it will automatically deserialize return values that were `serialize()`-ed on the server side, including proper `Date` object recovery.
+
+```ts
+// Server-side (Apps Script)
+// const getAppData = () => serialize({ updatedAt: new Date(), user: 'Alice' });
+
+// Client-side
+export const gas = getPromisedServerScripts<ServerScripts>({
+  parseJson: true
+});
+
+async function fetchData() {
+  // The return value is inferred as the original object type instead of `any`
+  // Date objects are also automatically recovered
+  const result = await gas.getAppData();
+  console.log(result.user); // 'Alice' (string)
+  console.log(result.updatedAt instanceof Date); // true
+}
 ```
 
 ## Contributing

package/dist/cli.cjs

@@ -26,7 +26,7 @@ function _interopNamespaceCompat(e) {
 
 const path__namespace = /*#__PURE__*/_interopNamespaceCompat(path);
 
-const version = "0.4.1";
+const version = "0.5.0";
 
 const parseArgs = async (command) => {
   const cliOpts = command.opts();

package/dist/cli.mjs

@@ -10,7 +10,7 @@ import 'node:fs';
 import 'ts-morph';
 import 'jiti';
 
-const version = "0.4.1";
+const version = "0.5.0";
 
 const parseArgs = async (command) => {
   const cliOpts = command.opts();

package/dist/json.cjs

@@ -0,0 +1,21 @@
+'use strict';
+
+const isoDateRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$/;
+function dateReviver(_key, value) {
+  if (typeof value === "string" && isoDateRegex.test(value)) {
+    const date = new Date(value);
+    if (!Number.isNaN(date.getTime())) {
+      return date;
+    }
+  }
+  return value;
+}
+const serialize = (data) => {
+  return JSON.stringify(data);
+};
+const deserialize = (json) => {
+  return JSON.parse(json, dateReviver);
+};
+
+exports.deserialize = deserialize;
+exports.serialize = serialize;

package/dist/json.d.cts

@@ -0,0 +1,29 @@
+declare const __brand: unique symbol;
+/**
+ * シリアライズ前の型情報 `T` を保持したJSON文字列型。
+ * 単なる string ではなく、型システム上で元の型を記憶することで、
+ * 復元時に型安全なパース（anyを介さない復元）を可能にします。
+ */
+type JsonString<T> = string & {
+    [__brand]: T;
+};
+/**
+ * オブジェクトを型情報を保持したまま JSON 文字列に変換します。
+ * 戻り値は元の型 `T` を記憶した `JsonString<T>` となります。
+ *
+ * @param data 変換するオブジェクト
+ * @returns 型情報を保持した JSON 文字列
+ */
+declare const serialize: <T>(data: T) => JsonString<T>;
+/**
+ * `JsonString<T>` から元の型 `T` を型安全に復元します。
+ * 通常の `JSON.parse` と異なり、戻り値が `any` にならず、
+ * また ISO 8601 形式の文字列は自動的に `Date` オブジェクトへ変換されます。
+ *
+ * @param json 型情報を保持した JSON 文字列
+ * @returns 元の型 `T` に復元されたオブジェクト
+ */
+declare const deserialize: <T>(json: JsonString<T>) => T;
+
+export { deserialize, serialize };
+export type { JsonString };

package/dist/json.d.mts

@@ -0,0 +1,29 @@
+declare const __brand: unique symbol;
+/**
+ * シリアライズ前の型情報 `T` を保持したJSON文字列型。
+ * 単なる string ではなく、型システム上で元の型を記憶することで、
+ * 復元時に型安全なパース（anyを介さない復元）を可能にします。
+ */
+type JsonString<T> = string & {
+    [__brand]: T;
+};
+/**
+ * オブジェクトを型情報を保持したまま JSON 文字列に変換します。
+ * 戻り値は元の型 `T` を記憶した `JsonString<T>` となります。
+ *
+ * @param data 変換するオブジェクト
+ * @returns 型情報を保持した JSON 文字列
+ */
+declare const serialize: <T>(data: T) => JsonString<T>;
+/**
+ * `JsonString<T>` から元の型 `T` を型安全に復元します。
+ * 通常の `JSON.parse` と異なり、戻り値が `any` にならず、
+ * また ISO 8601 形式の文字列は自動的に `Date` オブジェクトへ変換されます。
+ *
+ * @param json 型情報を保持した JSON 文字列
+ * @returns 元の型 `T` に復元されたオブジェクト
+ */
+declare const deserialize: <T>(json: JsonString<T>) => T;
+
+export { deserialize, serialize };
+export type { JsonString };

package/dist/json.d.ts

@@ -0,0 +1,29 @@
+declare const __brand: unique symbol;
+/**
+ * シリアライズ前の型情報 `T` を保持したJSON文字列型。
+ * 単なる string ではなく、型システム上で元の型を記憶することで、
+ * 復元時に型安全なパース（anyを介さない復元）を可能にします。
+ */
+type JsonString<T> = string & {
+    [__brand]: T;
+};
+/**
+ * オブジェクトを型情報を保持したまま JSON 文字列に変換します。
+ * 戻り値は元の型 `T` を記憶した `JsonString<T>` となります。
+ *
+ * @param data 変換するオブジェクト
+ * @returns 型情報を保持した JSON 文字列
+ */
+declare const serialize: <T>(data: T) => JsonString<T>;
+/**
+ * `JsonString<T>` から元の型 `T` を型安全に復元します。
+ * 通常の `JSON.parse` と異なり、戻り値が `any` にならず、
+ * また ISO 8601 形式の文字列は自動的に `Date` オブジェクトへ変換されます。
+ *
+ * @param json 型情報を保持した JSON 文字列
+ * @returns 元の型 `T` に復元されたオブジェクト
+ */
+declare const deserialize: <T>(json: JsonString<T>) => T;
+
+export { deserialize, serialize };
+export type { JsonString };

package/dist/json.mjs

@@ -0,0 +1,18 @@
+const isoDateRegex = /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}.\d{3}Z$/;
+function dateReviver(_key, value) {
+  if (typeof value === "string" && isoDateRegex.test(value)) {
+    const date = new Date(value);
+    if (!Number.isNaN(date.getTime())) {
+      return date;
+    }
+  }
+  return value;
+}
+const serialize = (data) => {
+  return JSON.stringify(data);
+};
+const deserialize = (json) => {
+  return JSON.parse(json, dateReviver);
+};
+
+export { deserialize, serialize };

package/dist/promise.cjs

@@ -1,6 +1,9 @@
 'use strict';
 
-const getPromisedServerScripts = (mockupFunctions = {}) => {
+const json = require('./json.cjs');
+
+function getPromisedServerScripts(options = {}) {
+  const { mockupFunctions = {}, parseJson = false } = options;
   return new Proxy(mockupFunctions, {
     get(target, method) {
       if (!("google" in globalThis) || !google?.script?.run) {
@@ -10,10 +13,20 @@ const getPromisedServerScripts = (mockupFunctions = {}) => {
         throw Error(`Method ${method} not found in AppsScript.`);
       }
       return (...args) => new Promise((resolve, reject) => {
-        google.script.run.withSuccessHandler(resolve).withFailureHandler(reject)[method](...args);
+        google.script.run.withSuccessHandler((res) => {
+          if (parseJson && typeof res === "string") {
+            try {
+              resolve(json.deserialize(res));
+            } catch {
+              resolve(res);
+            }
+          } else {
+            resolve(res);
+          }
+        }).withFailureHandler(reject)[method](...args);
       });
     }
   });
-};
+}
 
 exports.getPromisedServerScripts = getPromisedServerScripts;

package/dist/promise.d.cts

@@ -1,8 +1,20 @@
+import { JsonString } from './json.cjs';
+
 type Promised<T> = {
     [K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<R> : T[K];
 };
+type UnwrapJson<T> = T extends JsonString<infer U> ? U : T;
+type PromisedWithJson<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<UnwrapJson<R>> : T[K];
+};
 type PartialScriptType<T> = Partial<Promised<T>>;
-declare const getPromisedServerScripts: <T extends Record<string, (...args: any[]) => any> = Omit<typeof google.script.run, "withSuccessHandler" | "withFailureHandler" | "withUserObject">>(mockupFunctions?: PartialScriptType<T>) => Promised<T>;
+type PartialScriptTypeWithJson<T> = Partial<PromisedWithJson<T>>;
+type GetPromisedServerScriptsOptions<T, IsJson extends boolean = boolean> = {
+    mockupFunctions?: IsJson extends true ? PartialScriptTypeWithJson<T> : PartialScriptType<T>;
+    parseJson?: IsJson;
+};
+declare function getPromisedServerScripts<T extends Record<string, (...args: any[]) => any> = Omit<typeof google.script.run, 'withSuccessHandler' | 'withFailureHandler' | 'withUserObject'>>(options: GetPromisedServerScriptsOptions<T, true>): PromisedWithJson<T>;
+declare function getPromisedServerScripts<T extends Record<string, (...args: any[]) => any> = Omit<typeof google.script.run, 'withSuccessHandler' | 'withFailureHandler' | 'withUserObject'>>(options?: GetPromisedServerScriptsOptions<T, false>): Promised<T>;
 
 export { getPromisedServerScripts };
-export type { PartialScriptType, Promised };
+export type { GetPromisedServerScriptsOptions, PartialScriptType, PartialScriptTypeWithJson, Promised, PromisedWithJson };

package/dist/promise.d.mts

@@ -1,8 +1,20 @@
+import { JsonString } from './json.mjs';
+
 type Promised<T> = {
     [K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<R> : T[K];
 };
+type UnwrapJson<T> = T extends JsonString<infer U> ? U : T;
+type PromisedWithJson<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<UnwrapJson<R>> : T[K];
+};
 type PartialScriptType<T> = Partial<Promised<T>>;
-declare const getPromisedServerScripts: <T extends Record<string, (...args: any[]) => any> = Omit<typeof google.script.run, "withSuccessHandler" | "withFailureHandler" | "withUserObject">>(mockupFunctions?: PartialScriptType<T>) => Promised<T>;
+type PartialScriptTypeWithJson<T> = Partial<PromisedWithJson<T>>;
+type GetPromisedServerScriptsOptions<T, IsJson extends boolean = boolean> = {
+    mockupFunctions?: IsJson extends true ? PartialScriptTypeWithJson<T> : PartialScriptType<T>;
+    parseJson?: IsJson;
+};
+declare function getPromisedServerScripts<T extends Record<string, (...args: any[]) => any> = Omit<typeof google.script.run, 'withSuccessHandler' | 'withFailureHandler' | 'withUserObject'>>(options: GetPromisedServerScriptsOptions<T, true>): PromisedWithJson<T>;
+declare function getPromisedServerScripts<T extends Record<string, (...args: any[]) => any> = Omit<typeof google.script.run, 'withSuccessHandler' | 'withFailureHandler' | 'withUserObject'>>(options?: GetPromisedServerScriptsOptions<T, false>): Promised<T>;
 
 export { getPromisedServerScripts };
-export type { PartialScriptType, Promised };
+export type { GetPromisedServerScriptsOptions, PartialScriptType, PartialScriptTypeWithJson, Promised, PromisedWithJson };

package/dist/promise.d.ts

@@ -1,8 +1,20 @@
+import { JsonString } from './json.js';
+
 type Promised<T> = {
     [K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<R> : T[K];
 };
+type UnwrapJson<T> = T extends JsonString<infer U> ? U : T;
+type PromisedWithJson<T> = {
+    [K in keyof T]: T[K] extends (...args: infer A) => infer R ? (...args: A) => Promise<UnwrapJson<R>> : T[K];
+};
 type PartialScriptType<T> = Partial<Promised<T>>;
-declare const getPromisedServerScripts: <T extends Record<string, (...args: any[]) => any> = Omit<typeof google.script.run, "withSuccessHandler" | "withFailureHandler" | "withUserObject">>(mockupFunctions?: PartialScriptType<T>) => Promised<T>;
+type PartialScriptTypeWithJson<T> = Partial<PromisedWithJson<T>>;
+type GetPromisedServerScriptsOptions<T, IsJson extends boolean = boolean> = {
+    mockupFunctions?: IsJson extends true ? PartialScriptTypeWithJson<T> : PartialScriptType<T>;
+    parseJson?: IsJson;
+};
+declare function getPromisedServerScripts<T extends Record<string, (...args: any[]) => any> = Omit<typeof google.script.run, 'withSuccessHandler' | 'withFailureHandler' | 'withUserObject'>>(options: GetPromisedServerScriptsOptions<T, true>): PromisedWithJson<T>;
+declare function getPromisedServerScripts<T extends Record<string, (...args: any[]) => any> = Omit<typeof google.script.run, 'withSuccessHandler' | 'withFailureHandler' | 'withUserObject'>>(options?: GetPromisedServerScriptsOptions<T, false>): Promised<T>;
 
 export { getPromisedServerScripts };
-export type { PartialScriptType, Promised };
+export type { GetPromisedServerScriptsOptions, PartialScriptType, PartialScriptTypeWithJson, Promised, PromisedWithJson };

package/dist/promise.mjs

@@ -1,4 +1,7 @@
-const getPromisedServerScripts = (mockupFunctions = {}) => {
+import { deserialize } from './json.mjs';
+
+function getPromisedServerScripts(options = {}) {
+  const { mockupFunctions = {}, parseJson = false } = options;
   return new Proxy(mockupFunctions, {
     get(target, method) {
       if (!("google" in globalThis) || !google?.script?.run) {
@@ -8,10 +11,20 @@ const getPromisedServerScripts = (mockupFunctions = {}) => {
         throw Error(`Method ${method} not found in AppsScript.`);
       }
       return (...args) => new Promise((resolve, reject) => {
-        google.script.run.withSuccessHandler(resolve).withFailureHandler(reject)[method](...args);
+        google.script.run.withSuccessHandler((res) => {
+          if (parseJson && typeof res === "string") {
+            try {
+              resolve(deserialize(res));
+            } catch {
+              resolve(res);
+            }
+          } else {
+            resolve(res);
+          }
+        }).withFailureHandler(reject)[method](...args);
       });
     }
   });
-};
+}
 
 export { getPromisedServerScripts };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ciderjs/gasnuki",
-  "version": "0.4.1",
+  "version": "0.5.0",
   "description": "Type definitions and utilities for Google Apps Script client-side API",
   "main": "dist/index.mjs",
   "types": "dist/index.d.ts",
@@ -22,6 +22,11 @@
       "types": "./dist/vite.d.ts",
       "import": "./dist/vite.mjs",
       "require": "./dist/vite.cjs"
+    },
+    "./json": {
+      "types": "./dist/json.d.ts",
+      "import": "./dist/json.mjs",
+      "require": "./dist/json.cjs"
     }
   },
   "scripts": {
@@ -45,7 +50,7 @@
     "@google/clasp"
   ],
   "author": "ciderjs/luth",
-  "license": "ISC",
+  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "git+ssh://git@github.com:luthpg/gasnuki.git"
@@ -62,12 +67,12 @@
     "ts-morph": "^27.0.2"
   },
   "devDependencies": {
-    "@biomejs/biome": "^2.3.10",
-    "@types/node": "^25.0.3",
+    "@biomejs/biome": "^2.3.11",
+    "@types/node": "^25.0.5",
     "@vitest/coverage-v8": "4.0.16",
     "typescript": "^5.9.3",
     "unbuild": "^3.6.1",
-    "vite": "^7.3.0",
+    "vite": "^7.3.1",
     "vitest": "4.0.16"
   },
   "peerDependencies": {