Debian Codegraph @

frontend/src/extensions.ts

raw
1 /**
2 * Fava extensions might contain their own Javascript code, this module
3 * contains the functionality to handle them.
4 */
5
6 import { get as store_get } from "svelte/store";
7
8 import { getUrlPath, urlForRaw } from "./helpers";
9 import { fetch } from "./lib/fetch";
10 import { log_error } from "./log";
11 import { extensions } from "./stores";
12
13 /** Helpers to make requests. */
14 export class ExtensionApi {
15 constructor(private readonly name: string) {}
16
17 /** Send a request to an extension endpoint. */
18 async request(
19 endpoint: string,
20 method: "GET" | "PUT" | "POST" | "DELETE",
21 params?: Record<string, string | number>,
22 body?: unknown,
23 output: "json" | "string" | "raw" = "json",
24 ): Promise<unknown> {
25 const $urlForRaw = store_get(urlForRaw);
26 const url = $urlForRaw(`extension/${this.name}/${endpoint}`, params);
27 let opts = {};
28 if (body != null) {
29 opts =
30 body instanceof FormData
31 ? { body }
32 : {
33 headers: { "Content-Type": "application/json" },
34 body: JSON.stringify(body),
35 };
36 }
37 const response = await fetch(url, { method, ...opts });
38 if (output === "json") {
39 return response.json();
40 }
41 if (output === "string") {
42 return response.text();
43 }
44 return response;
45 }
46
47 /** GET an endpoint with parameters and return JSON. */
48 async get(
49 endpoint: string,
50 params: Record<string, string>,
51 ): Promise<unknown> {
52 return this.request(endpoint, "GET", params, undefined);
53 }
54
55 /** GET an endpoint with a body and return JSON. */
56 async put(endpoint: string, body?: unknown): Promise<unknown> {
57 return this.request(endpoint, "PUT", undefined, body);
58 }
59
60 /** POST to an endpoint with a body and return JSON. */
61 async post(endpoint: string, body?: unknown): Promise<unknown> {
62 return this.request(endpoint, "POST", undefined, body);
63 }
64
65 /** DELETE an endpoint and return JSON. */
66 async delete(endpoint: string): Promise<unknown> {
67 return this.request(endpoint, "DELETE");
68 }
69 }
70
71 /** The context that an extensions handlers are called with. */
72 export interface ExtensionContext {
73 /** Helpers to make requests. */
74 api: ExtensionApi;
75 }
76
77 /**
78 * The Javascript code of a Fava extension should export an object of this type.
79 *
80 * The extension will be initialised when Fava loads by a call to init(). It can also
81 * provider handlers that are run on each subsequent page load (either all or just
82 * pages of the extension itself).
83 */
84 export interface ExtensionModule {
85 /** Initialise this Javascript module / run some code on the initial load. */
86 init?: (c: ExtensionContext) => void | Promise<void>;
87 /** Run some code after any Fava page has loaded. */
88 onPageLoad?: (c: ExtensionContext) => void;
89 /** Run some code after a page for this extension has loaded. */
90 onExtensionPageLoad?: (c: ExtensionContext) => void;
91 }
92
93 class ExtensionData {
94 constructor(
95 private readonly extension: ExtensionModule,
96 private readonly context: ExtensionContext,
97 ) {}
98
99 async init(): Promise<void> {
100 await this.extension.init?.(this.context);
101 }
102
103 onPageLoad(): void {
104 this.extension.onPageLoad?.(this.context);
105 }
106
107 onExtensionPageLoad(): void {
108 this.extension.onExtensionPageLoad?.(this.context);
109 }
110 }
111
112 async function loadExtensionModule(name: string): Promise<ExtensionData> {
113 const $urlForRaw = store_get(urlForRaw);
114 const url = $urlForRaw(`extension_js_module/${name}.js`);
115 const mod = await (import(url) as Promise<{ default?: ExtensionModule }>);
116 if (typeof mod.default === "object") {
117 return new ExtensionData(mod.default, { api: new ExtensionApi(name) });
118 }
119 throw new Error(
120 `Error importing module for extension ${name}: module must export "default" object`,
121 );
122 }
123
124 /** A map of all extensions modules that have been (requested to be) loaded already. */
125 const loaded_extensions = new Map<string, Promise<ExtensionData>>();
126
127 /** Get the extensions module - if it has not been imported yet, initialise it. */
128 async function getOrInitExtension(name: string): Promise<ExtensionData> {
129 const loaded_ext = loaded_extensions.get(name);
130 if (loaded_ext) {
131 return loaded_ext;
132 }
133 const ext_promise = loadExtensionModule(name);
134 loaded_extensions.set(name, ext_promise);
135 await (await ext_promise).init();
136 return ext_promise;
137 }
138
139 /**
140 * On page load, run check if the new page is an extension report page and run hooks.
141 */
142 export function handleExtensionPageLoad(): void {
143 const exts = store_get(extensions).filter((e) => e.has_js_module);
144 for (const { name } of exts) {
145 // Run the onPageLoad handler for all pages.
146 getOrInitExtension(name)
147 .then((m) => {
148 m.onPageLoad();
149 })
150 .catch(log_error);
151 }
152 const path = getUrlPath(window.location) ?? "";
153 if (path.startsWith("extension/")) {
154 for (const { name } of exts) {
155 if (path.startsWith(`extension/${name}`)) {
156 getOrInitExtension(name)
157 .then((m) => {
158 m.onExtensionPageLoad();
159 })
160 .catch(log_error);
161 }
162 }
163 }
164 }