@gasboost/client 0.1.0

package/dist/job/AppsScriptJobRunner.js

@@ -0,0 +1,93 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppsScriptJobRunner = void 0;
+class AppsScriptJobRunner {
+    queue;
+    jobs = [];
+    listeners = new Set();
+    MAX_CONCURRENT = 30;
+    running = false;
+    snapshot = null;
+    dirty = true;
+    constructor(queue) {
+        this.queue = queue;
+        this.queue.subscribe(this);
+    }
+    addJob(job) {
+        this.jobs.push(job);
+        this.notify();
+    }
+    getJobs() {
+        if (this.dirty || !this.snapshot) {
+            this.snapshot = [...this.jobs];
+            this.dirty = false;
+        }
+        return this.snapshot;
+    }
+    async run() {
+        if (this.running)
+            return;
+        this.running = true;
+        while (true) {
+            const runningCount = this.jobs.filter((j) => j.isRunning()).length;
+            if (runningCount >= this.MAX_CONCURRENT)
+                break;
+            const job = this.queue.dequeue();
+            if (!job)
+                break;
+            job.start();
+            this.notify();
+            job
+                .execute()
+                .then((result) => {
+                job.success(result);
+                const index = this.jobs.indexOf(job);
+                if (index !== -1) {
+                    this.jobs.splice(index, 1);
+                }
+            })
+                .catch((error) => {
+                job.fail(error);
+            })
+                .finally(() => {
+                this.notify();
+                this.running = false;
+                this.run();
+            });
+        }
+        this.running = false;
+    }
+    remove(jobId) {
+        const index = this.jobs.findIndex((job) => job.id === jobId);
+        if (index === -1) {
+            return;
+        }
+        this.jobs.splice(index, 1);
+        this.notify();
+    }
+    cancel(jobId) {
+        const job = this.jobs.find((job) => job.id === jobId);
+        if (!job || !job.cancel()) {
+            return;
+        }
+        this.queue.remove(jobId);
+        this.jobs.splice(this.jobs.indexOf(job), 1);
+        this.notify();
+    }
+    retry(jobId) {
+        const job = this.jobs.find((j) => j.id === jobId);
+        if (job) {
+            this.remove(job.id);
+            this.queue.enqueue(job.label, job.execute);
+        }
+    }
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    notify() {
+        this.dirty = true;
+        this.listeners.forEach((listener) => listener());
+    }
+}
+exports.AppsScriptJobRunner = AppsScriptJobRunner;

package/dist/job/AppsScriptJobStore.d.ts

@@ -0,0 +1,7 @@
+import { AppsScriptJob } from "./AppsScriptJob";
+import { AppsScriptJobRunner } from "./AppsScriptJobRunner";
+export interface AppsScriptJobStore {
+    subscribe: (listener: () => void) => () => void;
+    getSnapshot: () => AppsScriptJob<any>[];
+}
+export declare function appsScriptJobStore(runner: AppsScriptJobRunner): AppsScriptJobStore;

package/dist/job/AppsScriptJobStore.js

@@ -0,0 +1,9 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.appsScriptJobStore = appsScriptJobStore;
+function appsScriptJobStore(runner) {
+    return {
+        subscribe: runner.subscribe.bind(runner),
+        getSnapshot: runner.getJobs.bind(runner),
+    };
+}

package/dist/navigation/AppsScriptContainer.d.ts

@@ -0,0 +1,9 @@
+import { NavigationEntry } from "./NavigationEntry";
+export declare class AppsScriptContainer {
+    private entry;
+    private constructor();
+    static load(callback: (container: AppsScriptContainer) => void): void;
+    observe(handler: (entry: NavigationEntry) => void): void;
+    sync(entry: NavigationEntry): void;
+    current(): NavigationEntry;
+}

package/dist/navigation/AppsScriptContainer.js

@@ -0,0 +1,38 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppsScriptContainer = void 0;
+const google_1 = require("../google");
+const NavigationEntry_1 = require("./NavigationEntry");
+class AppsScriptContainer {
+    entry;
+    constructor(entry) {
+        this.entry = entry;
+    }
+    static load(callback) {
+        google_1.google.script.url.getLocation((location) => {
+            callback(new AppsScriptContainer(NavigationEntry_1.NavigationEntry.fromGoogle(location)));
+        });
+    }
+    observe(handler) {
+        google_1.google.script.history.setChangeHandler((event) => {
+            const entry = NavigationEntry_1.NavigationEntry.fromGoogle(event);
+            this.entry = entry;
+            handler(entry);
+        });
+    }
+    sync(entry) {
+        if (this.entry.equals(entry)) {
+            return;
+        }
+        this.entry = entry;
+        const parameters = {};
+        for (const key of new Set(entry.location.searchParams.keys())) {
+            parameters[key] = entry.location.searchParams.getAll(key);
+        }
+        google_1.google.script.history.push(entry.state, parameters, entry.location.hash.normalize());
+    }
+    current() {
+        return this.entry;
+    }
+}
+exports.AppsScriptContainer = AppsScriptContainer;

package/dist/navigation/AppsScriptHistoryPipeline.d.ts

@@ -0,0 +1,9 @@
+import { AppsScriptContainer } from "./AppsScriptContainer";
+import { AppsScriptIframe } from "./AppsScriptIframe";
+export declare class AppsScriptHistoryPipeline {
+    private readonly container;
+    private readonly iframe;
+    constructor(container: AppsScriptContainer, iframe: AppsScriptIframe);
+    static create(callback: (pipeline: AppsScriptHistoryPipeline) => void): void;
+    sync(): () => void;
+}

package/dist/navigation/AppsScriptHistoryPipeline.js

@@ -0,0 +1,28 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppsScriptHistoryPipeline = void 0;
+const AppsScriptContainer_1 = require("./AppsScriptContainer");
+const AppsScriptIframe_1 = require("./AppsScriptIframe");
+class AppsScriptHistoryPipeline {
+    container;
+    iframe;
+    constructor(container, iframe) {
+        this.container = container;
+        this.iframe = iframe;
+    }
+    static create(callback) {
+        AppsScriptContainer_1.AppsScriptContainer.load((container) => {
+            callback(new AppsScriptHistoryPipeline(container, new AppsScriptIframe_1.AppsScriptIframe()));
+        });
+    }
+    sync() {
+        this.iframe.sync(this.container.current());
+        this.container.observe((entry) => {
+            this.iframe.sync(entry);
+        });
+        return this.iframe.observe((entry) => {
+            this.container.sync(entry);
+        });
+    }
+}
+exports.AppsScriptHistoryPipeline = AppsScriptHistoryPipeline;

package/dist/navigation/AppsScriptIframe.d.ts

@@ -0,0 +1,9 @@
+import { NavigationEntry } from "./NavigationEntry";
+export declare class AppsScriptIframe {
+    private entry;
+    constructor();
+    observe(handler: (entry: NavigationEntry) => void): () => void;
+    sync(entry: NavigationEntry): void;
+    current(): NavigationEntry;
+    private read;
+}

package/dist/navigation/AppsScriptIframe.js

@@ -0,0 +1,45 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AppsScriptIframe = void 0;
+const HashProperty_1 = require("./HashProperty");
+const NavigationEntry_1 = require("./NavigationEntry");
+const NavigationLocation_1 = require("./NavigationLocation");
+class AppsScriptIframe {
+    entry;
+    constructor() {
+        this.entry = this.read();
+    }
+    observe(handler) {
+        const listener = () => {
+            const entry = this.read();
+            this.entry = entry;
+            handler(entry);
+        };
+        window.addEventListener("hashchange", listener);
+        window.addEventListener("popstate", listener);
+        return () => {
+            window.removeEventListener("hashchange", listener);
+            window.removeEventListener("popstate", listener);
+        };
+    }
+    sync(entry) {
+        if (this.entry.equals(entry)) {
+            return;
+        }
+        const hash = entry.location.hash.normalize();
+        const search = entry.location.searchParams.toString();
+        const nextHash = search ? `${hash}?${search}` : hash;
+        history.replaceState(entry.state, "", nextHash);
+        this.entry = entry;
+    }
+    current() {
+        return this.entry;
+    }
+    read() {
+        const hash = new HashProperty_1.HashProperty(window.location.hash);
+        const normalized = hash.toString().replace(/^#/, "");
+        const [, query = ""] = normalized.split("?");
+        return new NavigationEntry_1.NavigationEntry(history.state ?? {}, new NavigationLocation_1.NavigationLocation(hash, new URLSearchParams(query)));
+    }
+}
+exports.AppsScriptIframe = AppsScriptIframe;

package/dist/navigation/HashProperty.d.ts

@@ -0,0 +1,7 @@
+export declare class HashProperty {
+    private readonly value;
+    constructor(value: string);
+    normalize(): string;
+    equals(other: HashProperty): boolean;
+    toString(): string;
+}

package/dist/navigation/HashProperty.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.HashProperty = void 0;
+class HashProperty {
+    value;
+    constructor(value) {
+        this.value = value;
+    }
+    normalize() {
+        if (!this.value)
+            return "#/";
+        if (this.value.startsWith("#/"))
+            return this.value;
+        if (this.value.startsWith("#"))
+            return `#/${this.value.slice(1)}`;
+        if (this.value.startsWith("/"))
+            return `#${this.value}`;
+        return `#/${this.value}`;
+    }
+    equals(other) {
+        return this.normalize() === other.normalize();
+    }
+    toString() {
+        return this.normalize();
+    }
+}
+exports.HashProperty = HashProperty;

package/dist/navigation/NavigationEntry.d.ts

@@ -0,0 +1,9 @@
+import type { GoogleScriptHistoryEvent, GoogleScriptUrlLocation } from "../google";
+import { NavigationLocation } from "./NavigationLocation";
+export declare class NavigationEntry {
+    readonly state: Record<string, unknown>;
+    readonly location: NavigationLocation;
+    constructor(state: Record<string, unknown>, location: NavigationLocation);
+    static fromGoogle(source: GoogleScriptHistoryEvent | GoogleScriptUrlLocation): NavigationEntry;
+    equals(other: NavigationEntry): boolean;
+}

package/dist/navigation/NavigationEntry.js

@@ -0,0 +1,54 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NavigationEntry = void 0;
+const HashProperty_1 = require("./HashProperty");
+const NavigationLocation_1 = require("./NavigationLocation");
+class NavigationEntry {
+    state;
+    location;
+    constructor(state, location) {
+        this.state = state;
+        this.location = location;
+    }
+    static fromGoogle(source) {
+        const location = "location" in source ? source.location : source;
+        const state = "state" in source ? source.state : {};
+        const searchParams = new URLSearchParams();
+        for (const [key, values] of Object.entries(location.parameters)) {
+            for (const value of values) {
+                searchParams.append(key, value);
+            }
+        }
+        return new NavigationEntry(state, new NavigationLocation_1.NavigationLocation(new HashProperty_1.HashProperty(location.hash), searchParams));
+    }
+    equals(other) {
+        const equalsState = (left, right) => {
+            if (Object.is(left, right)) {
+                return true;
+            }
+            if (typeof left !== "object" ||
+                left === null ||
+                typeof right !== "object" ||
+                right === null) {
+                return false;
+            }
+            if (Array.isArray(left) || Array.isArray(right)) {
+                if (!Array.isArray(left) || !Array.isArray(right)) {
+                    return false;
+                }
+                return (left.length === right.length &&
+                    left.every((value, index) => equalsState(value, right[index])));
+            }
+            const leftObject = left;
+            const rightObject = right;
+            const leftKeys = Object.keys(leftObject);
+            const rightKeys = Object.keys(rightObject);
+            return (leftKeys.length === rightKeys.length &&
+                leftKeys.every((key) => Object.hasOwn(rightObject, key) &&
+                    equalsState(leftObject[key], rightObject[key])));
+        };
+        return (equalsState(this.state, other.state) &&
+            this.location.equals(other.location));
+    }
+}
+exports.NavigationEntry = NavigationEntry;

package/dist/navigation/NavigationLocation.d.ts

@@ -0,0 +1,8 @@
+import { HashProperty } from "./HashProperty";
+export declare class NavigationLocation {
+    readonly hash: HashProperty;
+    readonly searchParams: URLSearchParams;
+    constructor(hash: HashProperty, searchParams: URLSearchParams);
+    equals(other: NavigationLocation): boolean;
+    private normalizeSearchParams;
+}

package/dist/navigation/NavigationLocation.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NavigationLocation = void 0;
+class NavigationLocation {
+    hash;
+    searchParams;
+    constructor(hash, searchParams) {
+        this.hash = hash;
+        this.searchParams = searchParams;
+    }
+    equals(other) {
+        const thisHash = this.hash.normalize().split("?")[0];
+        const otherHash = other.hash.normalize().split("?")[0];
+        if (thisHash !== otherHash) {
+            return false;
+        }
+        const thisKeys = [...new Set(this.searchParams.keys())].sort();
+        const otherKeys = [...new Set(other.searchParams.keys())].sort();
+        if (thisKeys.length !== otherKeys.length) {
+            return false;
+        }
+        return thisKeys.every((key, index) => {
+            if (key !== otherKeys[index]) {
+                return false;
+            }
+            const thisValues = this.searchParams.getAll(key);
+            const otherValues = other.searchParams.getAll(key);
+            return (thisValues.length === otherValues.length &&
+                thisValues.every((value, valueIndex) => value === otherValues[valueIndex]));
+        });
+    }
+    normalizeSearchParams(searchParams) {
+        const keys = [...new Set(searchParams.keys())].sort();
+        const normalized = new URLSearchParams();
+        for (const key of keys) {
+            for (const value of searchParams.getAll(key)) {
+                normalized.append(key, value);
+            }
+        }
+        return normalized.toString();
+    }
+}
+exports.NavigationLocation = NavigationLocation;

package/package.json

@@ -0,0 +1,20 @@
+{
+  "name": "@gasboost/client",
+  "version": "0.1.0",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "devDependencies": {
+    "jsdom": "^30.0.1"
+  },
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run --config vitest.config.mts"
+  }
+}

package/src/AppsScriptClient.ts

@@ -0,0 +1,81 @@
+import { google } from "./google";
+import { AppsScriptJob } from "./job/AppsScriptJob";
+import { AppsScriptJobQueue } from "./job/AppsScriptJobQueue";
+import { AppsScriptJobRunner } from "./job/AppsScriptJobRunner";
+import { appsScriptJobStore } from "./job/AppsScriptJobStore";
+
+type RpcResponse = {
+  contents: string;
+};
+
+type RpcDefinition = {
+  args: unknown[];
+  result: unknown;
+};
+
+type RpcApp = Record<string, RpcDefinition>;
+
+type AppsScriptClient<TApp extends RpcApp> = {
+  [K in keyof TApp]: TApp[K] extends {
+    args: infer TArgs extends unknown[];
+    result: infer TResult;
+  }
+    ? (...args: TArgs) => Promise<TResult>
+    : never;
+};
+
+export const appsScriptTransport = {
+  call(name: string, args: unknown[]): Promise<RpcResponse> {
+    return new Promise((resolve, reject) => {
+      google.script.run
+        .withSuccessHandler(resolve)
+        .withFailureHandler(reject)
+        [name](...args);
+    });
+  },
+};
+
+interface AppsScriptJobs {
+  start: <T>(label: string, execute: () => Promise<T>) => Promise<T>;
+  cancel: (jobId: string) => void;
+  retry: (jobId: string) => void;
+  subscribe: (listener: () => void) => () => void;
+  getSnapshot: () => AppsScriptJob<any>[];
+}
+
+export function appsScriptClient<TApp extends RpcApp>(): {
+  client: AppsScriptClient<TApp>;
+  jobs: AppsScriptJobs;
+} {
+  const jobQueue = new AppsScriptJobQueue();
+  const jobRunner = new AppsScriptJobRunner(jobQueue);
+  const jobStore = appsScriptJobStore(jobRunner);
+
+  const client = new Proxy(
+    {},
+    {
+      get(_target, property) {
+        if (typeof property !== "string") {
+          return undefined;
+        }
+
+        return (...args: unknown[]) => {
+          return jobQueue.enqueue(property, async () => {
+            const res = await appsScriptTransport.call(property, args);
+            return JSON.parse(res.contents);
+          });
+        };
+      },
+    },
+  ) as AppsScriptClient<TApp>;
+
+  const jobs = {
+    start: jobQueue.enqueue.bind(jobQueue),
+    cancel: jobRunner.cancel.bind(jobRunner),
+    retry: jobRunner.retry.bind(jobRunner),
+    subscribe: jobStore.subscribe.bind(jobStore),
+    getSnapshot: jobStore.getSnapshot.bind(jobStore),
+  };
+
+  return { client, jobs };
+}

package/src/google.ts

@@ -0,0 +1,55 @@
+export type GoogleScriptRun = {
+  withSuccessHandler<T = unknown>(
+    callback: (result: T) => void,
+  ): GoogleScriptRun;
+  withFailureHandler(callback: (error: Error) => void): GoogleScriptRun;
+  // GAS は run.任意のサーバー関数名(...) を呼ぶので index signature を持たせる
+  [serverFunctionName: string]: any;
+};
+
+export type GoogleScriptHistoryEvent = {
+  state: Record<string, unknown>;
+  location: {
+    hash: string;
+    parameter: Record<string, string>;
+    parameters: Record<string, string[]>;
+  };
+};
+
+export type GoogleScriptUrlLocation = {
+  hash: string;
+  parameter: Record<string, string>;
+  parameters: Record<string, string[]>;
+};
+
+export type GoogleApi = {
+  script: {
+    run: GoogleScriptRun;
+    history: {
+      push: (
+        stateObject: Record<string, unknown>,
+        params: Record<string, unknown>,
+        hash: string,
+      ) => void;
+      replace: (
+        stateObject: Record<string, unknown>,
+        params: Record<string, unknown>,
+        hash: string,
+      ) => void;
+      setChangeHandler: (
+        callback: (event: GoogleScriptHistoryEvent) => void,
+      ) => void;
+    };
+    url: {
+      getLocation: (
+        callback: (location: GoogleScriptUrlLocation) => void,
+      ) => void;
+    };
+  };
+};
+
+/**
+ * google.script.* は Apps Script のランタイムが注入するグローバル。
+ * ここでは「型付きで参照」だけ提供する。
+ */
+export const google = (globalThis as any).google as GoogleApi;

package/src/index.ts

@@ -0,0 +1,4 @@
+export { appsScriptClient } from "./AppsScriptClient";
+export type { AppsScriptJob } from "./job/AppsScriptJob";
+export { AppsScriptJobStore } from "./job/AppsScriptJobStore";
+export { AppsScriptHistoryPipeline } from "./navigation/AppsScriptHistoryPipeline";

package/src/job/AppsScriptJob.ts

@@ -0,0 +1,85 @@
+export class AppsScriptJob<T> {
+  private _startedAt: Date | null = null;
+  private _endedAt: Date | null = null;
+  private _result: T | null = null;
+  private _error: unknown | null = null;
+
+  constructor(
+    public readonly label: string,
+    public readonly execute: () => Promise<T>,
+    private resolve: (value: T) => void,
+    private reject: (reason?: any) => void,
+    public readonly id: string = crypto.randomUUID(),
+    public readonly createdAt: Date = new Date(),
+  ) {}
+
+  start() {
+    this._startedAt = new Date();
+  }
+
+  success(result: T) {
+    this._endedAt = new Date();
+    this._result = result;
+    this.resolve(result);
+  }
+
+  fail(error: unknown) {
+    this._endedAt = new Date();
+    this._error = error;
+    this.reject(error);
+  }
+
+  public get endedAt() {
+    return this._endedAt;
+  }
+
+  public get result() {
+    return this._result;
+  }
+
+  public get error() {
+    return this._error;
+  }
+
+  public isPending() {
+    return this._startedAt === null;
+  }
+
+  public isRunning() {
+    return this._startedAt !== null && this._endedAt === null;
+  }
+
+  public isSuccess() {
+    return this._endedAt !== null && this._error === null;
+  }
+
+  public isFailed() {
+    return this._endedAt !== null && this._error !== null;
+  }
+
+  public get status() {
+    if (this.isPending()) return "pending";
+    if (this.isRunning()) return "running";
+    if (this.isSuccess()) return "success";
+    if (this.isFailed()) return "failed";
+    return "unknown";
+  }
+
+  public cancel(): boolean {
+    if (!this.isPending()) {
+      return false;
+    }
+
+    const error = new AppsScriptJobCancelledError();
+    this.fail(error);
+
+    return true;
+  }
+}
+
+export class AppsScriptJobCancelledError extends Error {
+  constructor() {
+    super("Job cancelled");
+    this.name = "AppsScriptJobCancelledError";
+  }
+}