@procedures/browser 0.55.1 → 0.55.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -0,0 +1,176 @@
1
+ /**
2
+ * The profiles of the Chromium browsers on the disk: Google Chrome, Microsoft Edge and Chromium.
3
+ * This file finds the folders of the user data of each browser. Then it finds the bookmarks files of
4
+ * each profile in them, with the names of the profiles, and reads a file. The parse is in `bookmarks.ts`.
5
+ * This file uses Node.js, so only the root entry exports it.
6
+ */
7
+
8
+ import { readFile, readdir, stat } from "node:fs/promises";
9
+ import { join, posix, win32 } from "node:path";
10
+ import {
11
+ BOOKMARK_FILES,
12
+ MAX_BOOKMARKS_BYTES,
13
+ parseChromeBookmarks,
14
+ profileNames,
15
+ type BookmarkSource,
16
+ type ChromeBookmarks,
17
+ type ParseChromeBookmarksOptions,
18
+ } from "./bookmarks.js";
19
+
20
+ /** The file operations of the search and of the read. A test gives files in memory. */
21
+ export interface FileAccess {
22
+ /** This function gives the names in a folder, or no names when the folder does not exist. */
23
+ list(folder: string): Promise<readonly string[]>;
24
+ /** This function gives the size of a file in bytes, or `undefined` when the file does not exist. */
25
+ size(file: string): Promise<number | undefined>;
26
+ /** This function gives the text of a file in UTF-8. */
27
+ read(file: string): Promise<string>;
28
+ }
29
+
30
+ /**
31
+ * The file operations on the disk. `list` gives no names for each error, not only for a missing
32
+ * folder: also for a folder that it cannot read (`EACCES`). `size` gives `undefined` for each error
33
+ * and for a path that is not a file. `read` throws the error of the disk.
34
+ */
35
+ export const diskFileAccess: FileAccess = {
36
+ list: async (folder) => {
37
+ try {
38
+ return await readdir(folder);
39
+ } catch {
40
+ return [];
41
+ }
42
+ },
43
+ size: async (file) => {
44
+ try {
45
+ const found = await stat(file);
46
+ return found.isFile() ? found.size : undefined;
47
+ } catch {
48
+ return undefined;
49
+ }
50
+ },
51
+ read: (file) => readFile(file, "utf8"),
52
+ };
53
+
54
+ /**
55
+ * The key of a Chromium browser that keeps its profiles in a folder of user data. These are the
56
+ * browsers that `findBrowser` finds. The key is the first part of the id of a bookmarks file.
57
+ */
58
+ export type ProfileBrowser = "chrome" | "edge" | "chromium";
59
+
60
+ /** The browsers of `browserDataFolders`, in the order of its result. */
61
+ export const PROFILE_BROWSERS: readonly ProfileBrowser[] = ["chrome", "edge", "chromium"];
62
+
63
+ /** A folder of the user data of a browser. Each profile of the browser is a folder in it. */
64
+ export interface BrowserDataFolder {
65
+ /** The key of the browser, for example `chrome`. Another key, for example `brave`, is also correct. */
66
+ readonly browser: string;
67
+ /** The path of the folder. */
68
+ readonly folder: string;
69
+ }
70
+
71
+ /** The parts of the path of the user data of each browser, on each platform. */
72
+ const DATA_PATHS: Readonly<Record<ProfileBrowser, { readonly windows: readonly string[]; readonly mac: readonly string[]; readonly linux: string }>> = {
73
+ chrome: { windows: ["Google", "Chrome", "User Data"], mac: ["Google", "Chrome"], linux: "google-chrome" },
74
+ edge: { windows: ["Microsoft", "Edge", "User Data"], mac: ["Microsoft Edge"], linux: "microsoft-edge" },
75
+ chromium: { windows: ["Chromium", "User Data"], mac: ["Chromium"], linux: "chromium" },
76
+ };
77
+
78
+ /**
79
+ * This function gives the folders of the user data of the browsers for a platform. Windows uses
80
+ * `LOCALAPPDATA`, macOS uses `~/Library/Application Support`, and Linux uses `XDG_CONFIG_HOME` or `~/.config`.
81
+ * The function reads no file, so a folder in the result can be absent.
82
+ */
83
+ export function browserDataFolders(
84
+ platform: NodeJS.Platform,
85
+ env: Readonly<Record<string, string | undefined>>,
86
+ home: string,
87
+ browsers: readonly ProfileBrowser[] = PROFILE_BROWSERS,
88
+ ): BrowserDataFolder[] {
89
+ if (platform === "win32") {
90
+ const local = env["LOCALAPPDATA"] ?? win32.join(home, "AppData", "Local");
91
+ return browsers.map((browser) => ({ browser, folder: win32.join(local, ...DATA_PATHS[browser].windows) }));
92
+ }
93
+ if (platform === "darwin") {
94
+ const support = posix.join(home, "Library", "Application Support");
95
+ return browsers.map((browser) => ({ browser, folder: posix.join(support, ...DATA_PATHS[browser].mac) }));
96
+ }
97
+ const config = env["XDG_CONFIG_HOME"] ?? posix.join(home, ".config");
98
+ return browsers.map((browser) => ({ browser, folder: posix.join(config, DATA_PATHS[browser].linux) }));
99
+ }
100
+
101
+ /** A profile folder has the name `Default` or `Profile <n>`. The guest and system profiles have no bookmarks. */
102
+ const PROFILE = /^(Default|Profile \d+)$/;
103
+
104
+ /** This function gives the order of two profile folders: `Default` first, then `Profile <n>` by the number. */
105
+ function profileOrder(a: string, b: string): number {
106
+ const number = (name: string): number => (name === "Default" ? 0 : Number(name.slice("Profile ".length)));
107
+ return number(a) - number(b);
108
+ }
109
+
110
+ /** A bookmarks file that the search found, with its browser, its profile folder and its path. */
111
+ export interface BookmarkFile extends BookmarkSource {
112
+ /** The key of the browser of the profile, for example `chrome` or `edge`. */
113
+ readonly browser: string;
114
+ /** The name of the folder of the profile, for example `Default` or `Profile 2`. */
115
+ readonly profile: string;
116
+ /** The path of the file. */
117
+ readonly path: string;
118
+ /** The size of the file in bytes, at the time of the search. A file over `MAX_BOOKMARKS_BYTES` is not a bookmarks file. */
119
+ readonly size: number;
120
+ }
121
+
122
+ /**
123
+ * This function finds the bookmarks files of the profiles in the folders of the user data, in the
124
+ * order of the folders. In a folder, it gives `Default` first, then `Profile <n>` by the number. The
125
+ * file `Local State` gives the names of the profiles. Without it, a profile has the name of its folder.
126
+ * The id of a file starts with the key of its browser, so the files of two browsers have different ids.
127
+ */
128
+ export async function findBookmarkFiles(folders: readonly BrowserDataFolder[], files: FileAccess = diskFileAccess): Promise<BookmarkFile[]> {
129
+ const found: BookmarkFile[] = [];
130
+ for (const { browser, folder } of folders) {
131
+ let names = new Map<string, string>();
132
+ try {
133
+ names = profileNames(JSON.parse(await files.read(join(folder, "Local State"))));
134
+ } catch {
135
+ // A missing or broken file Local State gives the names of the folders
136
+ }
137
+ const profiles = new Set([...names.keys(), ...(await files.list(folder))].filter((name) => PROFILE.test(name)));
138
+ for (const profile of [...profiles].sort(profileOrder)) {
139
+ for (const [file, kind] of Object.entries(BOOKMARK_FILES)) {
140
+ const path = join(folder, profile, file);
141
+ const size = await files.size(path);
142
+ if (size === undefined) continue;
143
+ found.push({ id: `${browser}:${profile}:${file}`, name: names.get(profile) ?? profile, kind, browser, profile, path, size });
144
+ }
145
+ }
146
+ }
147
+ return found;
148
+ }
149
+
150
+ /**
151
+ * This function reads and parses a bookmarks file that `findBookmarkFiles` found. It reads the size
152
+ * again, because the file can change after the search. It refuses a file over `MAX_BOOKMARKS_BYTES`
153
+ * before the read. The default prefix of the keys is the id of the file and a colon, so the keys of
154
+ * two files are different.
155
+ *
156
+ * @throws Error when the file is not there, is too large, is not JSON or has no roots
157
+ */
158
+ export async function readBookmarkFile(
159
+ file: Pick<BookmarkFile, "id" | "path">,
160
+ files: FileAccess = diskFileAccess,
161
+ options: ParseChromeBookmarksOptions = {},
162
+ ): Promise<ChromeBookmarks> {
163
+ const size = await files.size(file.path);
164
+ if (size === undefined) throw new Error(`The file ${file.path} is not there now.`);
165
+ if (size > MAX_BOOKMARKS_BYTES) {
166
+ throw new Error(`The file ${file.path} has ${size} bytes. A bookmarks file has ${MAX_BOOKMARKS_BYTES} bytes at most.`);
167
+ }
168
+ const text = await files.read(file.path);
169
+ let value: unknown;
170
+ try {
171
+ value = JSON.parse(text);
172
+ } catch (error) {
173
+ throw new Error(`The file ${file.path} is not JSON, so it is not a bookmarks file.`, { cause: error });
174
+ }
175
+ return parseChromeBookmarks(value, { prefix: options.prefix ?? `${file.id}:` });
176
+ }
package/src/run.ts CHANGED
@@ -85,27 +85,63 @@ function lastLines(text: string, count = 5): string {
85
85
  return text.trim().split(/\r?\n/).slice(-count).join("\n");
86
86
  }
87
87
 
88
+ /**
89
+ * This function removes a folder and its content. It tries again 3 times, 100 ms apart, because
90
+ * Windows can hold a file for a short time after the browser stops. A removal that fails leaves the
91
+ * folder and does not throw. Thus it does not hide the result or the error of the caller.
92
+ */
93
+ function removeFolder(path: string): void {
94
+ try {
95
+ rmSync(path, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
96
+ } catch {
97
+ // The folder stays in the temporary folder of the system
98
+ }
99
+ }
100
+
101
+ /**
102
+ * This function makes a new temporary folder, gives its path to `use`, and then removes the folder,
103
+ * also when `use` throws. The name of the folder starts with `prefix`. The folder is in `folder`,
104
+ * else in the temporary folder of the system. Each temporary folder of this package uses this function.
105
+ */
106
+ export async function withTemporaryFolder<T>(prefix: string, folder: string | undefined, use: (path: string) => Promise<T>): Promise<T> {
107
+ const path = mkdtempSync(join(folder ?? tmpdir(), prefix));
108
+ try {
109
+ return await use(path);
110
+ } finally {
111
+ removeFolder(path);
112
+ }
113
+ }
114
+
88
115
  /**
89
116
  * This function starts the browser one time for a render, and gives the path and the size of the
90
117
  * file. It throws when it finds no browser, at the time limit and after a cancel. It also throws
91
118
  * when the file is missing, empty or not of the kind of the render.
92
119
  *
93
120
  * An existing output file changes only after the check of the new file. Thus a failed render keeps
94
- * an old output file.
121
+ * an old output file. Without the option `output`, the file goes in a new temporary folder. This
122
+ * folder stays after a success, and goes after a failure.
95
123
  */
96
124
  export async function headlessRender(render: HeadlessRender, source: PageSource, options: HeadlessOptions): Promise<RenderResult> {
97
125
  const browser = findBrowser(options);
98
126
  if (browser === undefined) {
99
127
  throw new Error(`No browser found. Install Microsoft Edge, Google Chrome or Chromium, or set ${BROWSER_ENV} to the browser program.`);
100
128
  }
101
-
102
- const work = mkdtempSync(join(tmpdir(), render.prefix));
103
- const profile = join(work, "profile");
104
- const htmlFile = join(work, "page.html");
105
- const output = resolve(options.output ?? join(work, render.file));
106
- const written = join(work, render.file);
107
- let made = false;
129
+ if (options.output !== undefined) return renderOnce(render, source, options, browser, resolve(options.output));
130
+ const kept = mkdtempSync(join(tmpdir(), render.prefix));
108
131
  try {
132
+ return await renderOnce(render, source, options, browser, join(kept, render.file));
133
+ } catch (error) {
134
+ removeFolder(kept);
135
+ throw error;
136
+ }
137
+ }
138
+
139
+ /** This function starts the browser in a temporary folder that always goes, and copies the checked file to `output`. */
140
+ function renderOnce(render: HeadlessRender, source: PageSource, options: HeadlessOptions, browser: string, output: string): Promise<RenderResult> {
141
+ return withTemporaryFolder(render.prefix, undefined, async (work) => {
142
+ const profile = join(work, "profile");
143
+ const htmlFile = join(work, "page.html");
144
+ const written = join(work, render.file);
109
145
  let page: string;
110
146
  if ("html" in source) {
111
147
  writeFileSync(htmlFile, source.html, "utf8");
@@ -136,17 +172,8 @@ export async function headlessRender(render: HeadlessRender, source: PageSource,
136
172
  throw new Error(`The browser made no ${render.noun} (exit code ${result.exitCode})${detail ? `: ${detail}` : ""}`);
137
173
  }
138
174
  if (!render.isValid(written)) throw new Error(`The file ${output} is not a ${render.noun}`);
139
- // The temporary folder goes in `finally`, so a copy is enough, also across two drives
140
- if (written !== output) copyFileSync(written, output);
141
- made = true;
175
+ // The temporary folder goes after this function, so a copy is enough, also across two drives
176
+ copyFileSync(written, output);
142
177
  return { path: output, bytes, browser };
143
- } finally {
144
- // The temporary page and profile go. A default output stays in its folder after a success.
145
- if (made && options.output === undefined) {
146
- rmSync(profile, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
147
- rmSync(htmlFile, { force: true });
148
- } else {
149
- rmSync(work, { recursive: true, force: true, maxRetries: 3, retryDelay: 100 });
150
- }
151
- }
178
+ });
152
179
  }
package/src/screenshot.ts CHANGED
@@ -4,8 +4,9 @@
4
4
  * writes a PNG, JPEG or WebP picture of the window.
5
5
  */
6
6
 
7
- import { extname } from "node:path";
8
- import { headlessRender, readHead, type HeadlessOptions, type HeadlessRender, type PageSource, type RenderResult } from "./run.js";
7
+ import { readFileSync } from "node:fs";
8
+ import { extname, join } from "node:path";
9
+ import { headlessRender, readHead, withTemporaryFolder, type HeadlessOptions, type HeadlessRender, type PageSource, type RenderResult } from "./run.js";
9
10
 
10
11
  /** The formats of a screenshot. The browser chooses the format from the extension of the file. */
11
12
  export type ScreenshotFormat = "png" | "jpeg" | "webp";
@@ -139,3 +140,34 @@ export async function renderScreenshot(options: RenderScreenshotOptions): Promis
139
140
  };
140
141
  return { ...(await headlessRender(render, source, options)), format };
141
142
  }
143
+
144
+ /** The options of `renderScreenshotBytes`: the options of `renderScreenshot`, with no `output`. */
145
+ export interface RenderScreenshotBytesOptions extends Omit<RenderScreenshotOptions, "output"> {
146
+ /** The folder that gets the temporary folder of the picture. The default is the temporary folder of the system. */
147
+ readonly folder?: string | undefined;
148
+ }
149
+
150
+ /** The result of `renderScreenshotBytes`: the picture, its format and the browser program. */
151
+ export interface RenderScreenshotBytesResult {
152
+ /** The bytes of the picture. In Node.js, the value is a `Buffer`. */
153
+ readonly data: Uint8Array;
154
+ readonly format: ScreenshotFormat;
155
+ /** The browser program that made the picture. */
156
+ readonly browser: string;
157
+ }
158
+
159
+ /**
160
+ * This function loads a page in a headless browser, and gives the picture of the window as bytes.
161
+ * It has the options and the errors of `renderScreenshot`, with no `output`.
162
+ *
163
+ * The function writes the picture to a new temporary folder, and reads it. Then it removes the
164
+ * folder, also after an error. A folder that the system does not let it remove stays, and gives no error.
165
+ */
166
+ export async function renderScreenshotBytes(options: RenderScreenshotBytesOptions): Promise<RenderScreenshotBytesResult> {
167
+ const { folder, ...rest } = options;
168
+ const format = rest.format ?? "png";
169
+ return withTemporaryFolder("procedures-screenshot-bytes-", folder, async (work) => {
170
+ const { path, browser } = await renderScreenshot({ ...rest, format, output: join(work, `picture${SCREENSHOT_EXTENSIONS[format]}`) });
171
+ return { data: readFileSync(path), format, browser };
172
+ });
173
+ }