From 554d9b21007da02f6df7f78574b4e46b2940cb47 Mon Sep 17 00:00:00 2001
From: takker99 <37929109+takker99@users.noreply.github.com>
Date: Fri, 13 Aug 2021 20:15:41 +0900
Subject: [PATCH 1/4] =?UTF-8?q?:construction:=20=E5=9E=8B=E3=82=92?=
 =?UTF-8?q?=E8=89=B2=E3=80=85=E6=95=B4=E7=90=86?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

一部の`type`を`interface`に変えた
JSDocの一部を英語化した
IDにtype aliasを当てた
---
 api/response.ts      | 121 +++++++++++++++++--------------------------
 base.ts              |  29 ++++++++++-
 userscript.ts        |  17 +++---
 userscript/blocks.ts |   7 +--
 4 files changed, 87 insertions(+), 87 deletions(-)

diff --git a/api/response.ts b/api/response.ts
index 059b287..4f38047 100644
--- a/api/response.ts
+++ b/api/response.ts
@@ -1,23 +1,23 @@
 import { Omit } from "../utils.ts";
-import { Line } from "../base.ts";
+import {
+  CommitId,
+  Line,
+  Page as PageBase,
+  PageId,
+  ProjectId,
+  UserId,
+} from "../base.ts";
 import { NotFoundError, NotMemberError } from "./error.ts";
 
 /** 関連ページのメタデータ */
-export interface RelatedPage {
-  /** ページのid */ id: string;
-  /** ページのタイトル */ title: string;
-  /** ページのタイトルを小文字にして、` `を`_`に変換したもの */ titleLc: string;
-  /** ページのサムネイル画像 */ image: string;
-  /** ページのサムネイル本文。最大5行 */ descriptions: string[];
+export interface RelatedPage extends PageBase {
   /** ページ内のリンク */ linksLc: string[];
   /** おそらく被リンク数 */ linked: number;
-  /** ページの最終更新日時 */ updated: number;
-  /** おそらくページの閲覧日時 */ accessed: number;
 }
 
 /** user information */
 export interface User {
-  /** user id */ id: string;
+  id: UserId;
   /** user name */ name: string;
   /** user display name */ displayName: string;
   /** profile image URL */ photo: string;
@@ -33,21 +33,12 @@ export interface UserInfo extends User {
 }
 
 /** summary of page information */
-export interface PageSummary {
-  /** ページのid */ id: string;
-  /** ページのタイトル */ title: string;
-  /** ページのサムネイル画像
-   * 存在しなければ`null`
-  */
-  image: string | null;
-  /** ページのサムネイル本文。最大5行 */ descriptions: string[];
+export interface PageSummary extends PageBase {
   /** ピン留めされていたら1, されていなかったら0 */ pin: 0 | 1;
   /** ページの閲覧回数 */ views: number;
   /** おそらく被リンク数 */ linked: number;
-  /** 最新の編集コミットid */ commitId: string;
+  /** 最新の編集コミットid */ commitId: CommitId;
   /** ページの作成日時 */ created: number;
-  /** ページの最終更新日時 */ updated: number;
-  /** Date last visitedに使われる最終アクセス日時 */ accessed: number;
   /** page rank */ pageRank: number;
   /** Page historyの最終生成日時 */ snapshotCreated: number | null;
 }
@@ -74,20 +65,17 @@ export interface Page extends PageSummary {
 }
 
 /** the response type of https://scrpabox.io/api/pages/:projectname */
-export type PageListResponse =
-  | NotFoundError
-  | NotMemberError
-  | {
-    /** data取得先のproject名 */ projectName: string;
-    /** parameterに渡したskipと同じ */ skip: number;
-    /** parameterに渡したlimitと同じ */ limit: number;
-    /** projectの全ページ数 (中身のないページを除く) */ count: number;
-    /** 取得できたページ情報 */ pages: PageSummary[];
-  };
+export interface PageList {
+  /** data取得先のproject名 */ projectName: string;
+  /** parameterに渡したskipと同じ */ skip: number;
+  /** parameterに渡したlimitと同じ */ limit: number;
+  /** projectの全ページ数 (中身のないページを除く) */ count: number;
+  /** 取得できたページ情報 */ pages: PageSummary[];
+}
 
-/** project basic information */
-export interface Project {
-  id: string;
+/** project information which isn't joined */
+export interface NotMemberProject {
+  id: ProjectId;
   name: string;
   displayName: string;
   publicVisible: boolean;
@@ -98,31 +86,24 @@ export interface Project {
   image?: string;
   created: number;
   updated: number;
-  isMember: boolean;
-  plan?: string;
+  isMember: false;
 }
 
-/** the response type of https://scrpabox.io/api/projects/:projectname */
-export type ProjectResponse =
-  | NotFoundError
-  | NotMemberError
-  | (
-    & Omit<Omit<Project, "isMember">, "plan">
-    & ({ isMember: false } | {
-      isMember: true;
-      plan?: string | null;
-      users: UserInfo[];
-      admins: string[];
-      owner: string;
-      trialing: boolean;
-      trialMaxPages: number;
-      skipPayment: boolean;
-      uploadFileTo: "gcs";
-      uploadImaegTo: "gyazo" | "gcs";
-      emailAddressPatterns: string[];
-      backuped: number | null;
-    })
-  );
+/** project information which is joined */
+export interface MemberProject extends Omit<NotMemberProject, "isMember"> {
+  isMember: true;
+  plan?: string | null;
+  users: UserInfo[];
+  admins: UserId[];
+  owner: UserId;
+  trialing: boolean;
+  trialMaxPages: number;
+  skipPayment: boolean;
+  uploadFileTo: "gcs";
+  uploadImaegTo: "gyazo" | "gcs";
+  emailAddressPatterns: string[];
+  backuped: number | null;
+}
 
 /** the response type of https://scrapbox.io/api/users/me */
 export type UserResponse =
@@ -140,26 +121,20 @@ export type UserResponse =
   } & UserInfo);
 
 /** the response type of https://scrapbox.io/api/pages/:projectname/search/titles */
-export type LinksResponse =
-  | NotFoundError
-  | NotMemberError
-  | {
-    message: "Invalid pageId";
-  }
-  | {
-    /** page id */ id: string;
-    /** page title */ title: string;
-    /** 画像が存在するかどうか */ hasIcon: boolean;
-    /** ページの更新日時 */ updated: number;
-    /** ページ内のリンク */ links: string[];
-  }[];
+export interface SearchedTitle {
+  id: PageId;
+  /** page title */ title: string;
+  /** 画像が存在するかどうか */ hasIcon: boolean;
+  /** ページの更新日時 */ updated: number;
+  /** ページ内のリンク */ links: string[];
+}
 
 export type ProjectBackup = {
   name: string;
   displayName: string;
   exported: number;
   pages: {
-    id: string;
+    id: PageId;
     title: string;
     created: number;
     updated: number;
@@ -171,10 +146,10 @@ export type ProjectBackupWithMetadata = {
   displayName: string;
   exported: number;
   pages: {
-    id: string;
+    id: PageId;
     title: string;
     created: number;
     updated: number;
-    lines: { text: string; updated: number; created: number }[];
+    lines: Omit<Line, "id" | "userId">[];
   };
 };
diff --git a/base.ts b/base.ts
index 2e81319..de1f01d 100644
--- a/base.ts
+++ b/base.ts
@@ -1,8 +1,35 @@
 /** scrapboxの行のメタデータ */
 export interface Line {
-  /** 行のid */ id: string;
+  /** 行のid */ id: LineId;
   /** 行のテキスト */ text: string;
   /** 一番最後に行を編集した人のid */ userId: string;
   /** 行の作成日時 */ created: number;
   /** 行の最終更新日時 */ updated: number;
 }
+
+/** basic information about a page */
+export interface Page {
+  /** the id of a page */ id: PageId;
+  /** the title of a page */ title: string;
+  /** the thumbnail URL of a page if exists
+   *
+   * set to `null` if not exists
+  */
+  image: string | null;
+  /** the thumbnail text of a page.
+  * the maximum number of lines is 5.
+  * */ descriptions: string[];
+  /** ページの最終更新日時 */ updated: number;
+  /** Date last visitedに使われる最終アクセス日時 */ accessed: number;
+}
+
+/** the user id */
+export type UserId = string;
+/** the line id */
+export type LineId = string;
+/** the commit id */
+export type CommitId = string;
+/** the page id */
+export type PageId = string;
+/** the project id */
+export type ProjectId = string;
diff --git a/userscript.ts b/userscript.ts
index 6a5eec0..a918fc9 100644
--- a/userscript.ts
+++ b/userscript.ts
@@ -73,14 +73,14 @@ export type Scrapbox =
     };
   });
 
-export type PageBrief = {
-  exists: boolean;
-  hasIcon?: boolean;
-  id: string;
-  title: string;
-  titleLc: string;
-  updated: number;
-};
+export interface PageBrief {
+  /** true when the page has contents */ exists: boolean;
+  /** whether the page contains any image */ hasIcon?: boolean;
+  /** the page id */ id: string;
+  /** the page title */ title: string;
+  /** the converted page title */ titleLc: string;
+  /** updated time */ updated: number;
+}
 
 type TimeStamp = {
   addFormat: (format: string | (() => string)) => void;
@@ -111,6 +111,7 @@ type PageMenu = {
   >;
 };
 
+/** built-in UserScript events */
 export type eventName =
   | "lines:changed"
   | "page:changed"
diff --git a/userscript/blocks.ts b/userscript/blocks.ts
index 64ef814..74b5c62 100644
--- a/userscript/blocks.ts
+++ b/userscript/blocks.ts
@@ -1,12 +1,9 @@
 import { Node, NodeWithoutIndent } from "./nodes.ts";
+import { Line } from "../base.ts";
 
 export type ParsedLine =
+  & Line
   & {
-    text: string;
-    id: string;
-    userId: string;
-    updated: number;
-    created: number;
     section: {
       number: number;
       start: boolean;

From f0fc6abb8b7ce545249094da5600737caafafafd Mon Sep 17 00:00:00 2001
From: takker99 <37929109+takker99@users.noreply.github.com>
Date: Fri, 13 Aug 2021 20:30:04 +0900
Subject: [PATCH 2/4] :construction: Add `StringLc`

---
 api/response.ts | 4 ++--
 base.ts         | 6 ++++++
 userscript.ts   | 3 ++-
 3 files changed, 10 insertions(+), 3 deletions(-)

diff --git a/api/response.ts b/api/response.ts
index 4f38047..f08af48 100644
--- a/api/response.ts
+++ b/api/response.ts
@@ -5,13 +5,13 @@ import {
   Page as PageBase,
   PageId,
   ProjectId,
+  StringLc,
   UserId,
 } from "../base.ts";
-import { NotFoundError, NotMemberError } from "./error.ts";
 
 /** 関連ページのメタデータ */
 export interface RelatedPage extends PageBase {
-  /** ページ内のリンク */ linksLc: string[];
+  /** ページ内のリンク */ linksLc: StringLc[];
   /** おそらく被リンク数 */ linked: number;
 }
 
diff --git a/base.ts b/base.ts
index de1f01d..9522dec 100644
--- a/base.ts
+++ b/base.ts
@@ -33,3 +33,9 @@ export type CommitId = string;
 export type PageId = string;
 /** the project id */
 export type ProjectId = string;
+/** the formatted string
+ *
+ * format rule:
+ * - UPPER CASE -> upper_case
+ */
+export type StringLc = string;
diff --git a/userscript.ts b/userscript.ts
index a918fc9..4ceb004 100644
--- a/userscript.ts
+++ b/userscript.ts
@@ -1,4 +1,5 @@
 import { ParsedLine } from "./userscript/blocks.ts";
+import { StringLc } from "./base.ts";
 
 export type Layout =
   | "list"
@@ -78,7 +79,7 @@ export interface PageBrief {
   /** whether the page contains any image */ hasIcon?: boolean;
   /** the page id */ id: string;
   /** the page title */ title: string;
-  /** the converted page title */ titleLc: string;
+  titleLc: StringLc;
   /** updated time */ updated: number;
 }
 

From 875d4915593fcbd7940e5f26612eba2a5c588745 Mon Sep 17 00:00:00 2001
From: takker99 <37929109+takker99@users.noreply.github.com>
Date: Fri, 13 Aug 2021 20:32:33 +0900
Subject: [PATCH 3/4] :construction: Change some `type` to `interface`

---
 api/response.ts | 8 ++++----
 base.ts         | 2 +-
 2 files changed, 5 insertions(+), 5 deletions(-)

diff --git a/api/response.ts b/api/response.ts
index f08af48..3983182 100644
--- a/api/response.ts
+++ b/api/response.ts
@@ -129,7 +129,7 @@ export interface SearchedTitle {
   /** ページ内のリンク */ links: string[];
 }
 
-export type ProjectBackup = {
+export interface ProjectBackup {
   name: string;
   displayName: string;
   exported: number;
@@ -140,8 +140,8 @@ export type ProjectBackup = {
     updated: number;
     lines: string[];
   };
-};
-export type ProjectBackupWithMetadata = {
+}
+export interface ProjectBackupWithMetadata {
   name: string;
   displayName: string;
   exported: number;
@@ -152,4 +152,4 @@ export type ProjectBackupWithMetadata = {
     updated: number;
     lines: Omit<Line, "id" | "userId">[];
   };
-};
+}
diff --git a/base.ts b/base.ts
index 9522dec..b78698a 100644
--- a/base.ts
+++ b/base.ts
@@ -2,7 +2,7 @@
 export interface Line {
   /** 行のid */ id: LineId;
   /** 行のテキスト */ text: string;
-  /** 一番最後に行を編集した人のid */ userId: string;
+  /** 一番最後に行を編集した人のid */ userId: UserId;
   /** 行の作成日時 */ created: number;
   /** 行の最終更新日時 */ updated: number;
 }

From 38f45265f91d26d65470f628e734ab1fa1a6ba4d Mon Sep 17 00:00:00 2001
From: takker99 <37929109+takker99@users.noreply.github.com>
Date: Wed, 25 Aug 2021 11:53:32 +0900
Subject: [PATCH 4/4] :refactor: Change some type to interfaces

Add more JSDoc
---
 api/response.ts      | 28 ++++++++++----------
 userscript.ts        | 62 ++++++++++++++++++++++++++++----------------
 userscript/blocks.ts | 32 +++++++++++++----------
 3 files changed, 73 insertions(+), 49 deletions(-)

diff --git a/api/response.ts b/api/response.ts
index 3983182..9aee547 100644
--- a/api/response.ts
+++ b/api/response.ts
@@ -105,20 +105,22 @@ export interface MemberProject extends Omit<NotMemberProject, "isMember"> {
   backuped: number | null;
 }
 
+export interface GuestUser {
+  isGuest: true;
+  csrfToken: string;
+}
+
+export interface MemberUser extends UserInfo {
+  isGuest: false;
+  csrfToken: string;
+  config: {
+    userScript: boolean;
+    emacsBinding: boolean;
+  };
+}
+
 /** the response type of https://scrapbox.io/api/users/me */
-export type UserResponse =
-  | {
-    isGuest: true;
-    csrfToken: string;
-  }
-  | ({
-    isGuest: false;
-    csrfToken: string;
-    config: {
-      userScript: boolean;
-      emacsBinding: boolean;
-    };
-  } & UserInfo);
+export type UserResponse = GuestUser | MemberUser;
 
 /** the response type of https://scrapbox.io/api/pages/:projectname/search/titles */
 export interface SearchedTitle {
diff --git a/userscript.ts b/userscript.ts
index 4ceb004..176ae5a 100644
--- a/userscript.ts
+++ b/userscript.ts
@@ -34,22 +34,8 @@ export type Scrapbox =
       addSeparator: () => void;
       removeAllItems: () => void;
     };
-    addListener: (type: string, listener: () => void) => void;
-    on: (type: string, listener: () => void) => void;
-    removeListener: (type: string, listener: () => void) => void;
-    off: (type: string, listener: () => void) => void;
-    removeAllListeners: (type?: string) => void;
-    once: (type: string, listener: () => void) => void;
-    prependListener: (type: string, listener: () => void) => void;
-    prependOnceListener: (type: string, listener: () => void) => void;
-    listeners: (type: string) => (() => void)[];
-    rawListeners: (type: string) => (() => void)[];
-    listenerCount: (type: string) => number;
-    emit: (type: string) => void;
-    eventNames: () => string[];
-    getMexListeners: () => number;
-    setMexListeners: (length: number) => void;
   }
+  & UserScriptEvents
   & ({
     Layout:
       | "list"
@@ -74,6 +60,23 @@ export type Scrapbox =
     };
   });
 
+export interface UserScriptEvents {
+  addListener: (type: string, listener: () => void) => void;
+  on: (type: string, listener: () => void) => void;
+  removeListener: (type: string, listener: () => void) => void;
+  off: (type: string, listener: () => void) => void;
+  removeAllListeners: (type?: string) => void;
+  once: (type: string, listener: () => void) => void;
+  prependListener: (type: string, listener: () => void) => void;
+  prependOnceListener: (type: string, listener: () => void) => void;
+  listeners: (type: string) => (() => void)[];
+  rawListeners: (type: string) => (() => void)[];
+  listenerCount: (type: string) => number;
+  emit: (type: string) => void;
+  eventNames: () => string[];
+  getMexListeners: () => number;
+  setMexListeners: (length: number) => void;
+}
 export interface PageBrief {
   /** true when the page has contents */ exists: boolean;
   /** whether the page contains any image */ hasIcon?: boolean;
@@ -83,20 +86,35 @@ export interface PageBrief {
   /** updated time */ updated: number;
 }
 
-type TimeStamp = {
+export interface TimeStamp {
+  /** Add a timestamp format to Scrapbox
+   *
+   * @param format a format of timestamp. this follow the moment.js format. You can set a function which returns any string
+   */
   addFormat: (format: string | (() => string)) => void;
+  /** Remove all timestamp formats from Scrapbox
+   *
+   * These include default formats
+   */
   removeAllFormat: () => void;
-};
+}
 
-type AddItemProps = {
-  title: string | (() => string);
+export interface AddItemProps {
+  /** the title of a menu item */ title: string | (() => string);
+  /** the URL of an image which views on the left of the title */
   image?: string;
+  /** the event listener which is executed when the menu item is clicked */
   onClick: () => void;
-};
-type PageMenu = {
+}
+export interface PageMenu {
+  /** Add a menu item to a particular Page Menu button
+   *
+   * @param props information used for a menu item
+   */
   addItem: (
     props: AddItemProps,
   ) => void;
+  /** Add a separator to a particular Page Menu button */
   addSeparator: () => void;
   removeAllItems: () => void;
   menuName: string;
@@ -110,7 +128,7 @@ type PageMenu = {
       items: (AddItemProps & { separator: boolean })[];
     }
   >;
-};
+}
 
 /** built-in UserScript events */
 export type eventName =
diff --git a/userscript/blocks.ts b/userscript/blocks.ts
index 74b5c62..9835606 100644
--- a/userscript/blocks.ts
+++ b/userscript/blocks.ts
@@ -29,20 +29,24 @@ export type ParsedLine =
     nodes: Node[];
   });
 
-export type CodeBlock = {
-  lang: string;
-  filename?: string;
-  indent: number;
-  start: boolean;
-  end: boolean;
-};
-export type TableBlock = {
-  title: string;
-  cells: string[];
-  indent: number;
-  start: boolean;
-  end: boolean;
-};
+/**  the type which represents a line in a block */
+export interface Block {
+  /** the number of indents */ indent: number;
+  /** is the start line of this block */ start: boolean;
+  /** is the end line of this block */ end: boolean;
+}
+
+/**  the type which represents a line in a code block */
+export interface CodeBlock extends Block {
+  /** the language of the code block */ lang: string;
+  /** the file name of the code block */ filename?: string;
+}
+
+/**  the type which represents a line in a table block */
+export interface TableBlock extends Block {
+  /** the title of the table block */ title: string;
+  /** cells included in the present line */ cells: string[];
+}
 export type Helpfeel = {
   prefix: "?";
   entry: string;