@koona/kpin 0.0.0-stage → 0.1.0
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.
- package/LICENSE.md +9 -0
- package/README.md +63 -2
- package/bin/kpin.js +169 -0
- package/package.json +67 -4
- package/schema-1.json +259 -0
- package/src/address.js +180 -0
- package/src/index.d.ts +153 -0
- package/src/index.js +10 -0
- package/src/one-click.js +29 -0
- package/src/read.js +359 -0
- package/src/text.js +256 -0
package/src/read.js
ADDED
|
@@ -0,0 +1,359 @@
|
|
|
1
|
+
// Reading a `.kpin` file as the spec's "How a reader answers a file" and "Payload of pin / list"
|
|
2
|
+
// say: one answer per file, then the metadata, sections, links and feeds, with what was skipped
|
|
3
|
+
// counted. A reader of 1.0: it knows MINOR 0.
|
|
4
|
+
import { line, description, tag, TITLE_LEN, ITEM_TITLE_LEN, DESCRIPTION_LEN, LICENSE_LEN, GENERATOR_LEN } from "./text.js";
|
|
5
|
+
import { linkUrl, feedUrl, webAddress, repeatKey, utf8Length } from "./address.js";
|
|
6
|
+
|
|
7
|
+
/** A file is at most 2 MB, checked before it is parsed. */
|
|
8
|
+
export const MAX_BYTES = 2 * 1024 * 1024;
|
|
9
|
+
/** Items across all sections and the top level. */
|
|
10
|
+
export const MAX_ITEMS = 5000;
|
|
11
|
+
/** Entries of `sections`, with a name or without. */
|
|
12
|
+
export const MAX_SECTIONS = 200;
|
|
13
|
+
/** Tags per link, with those of its repeats. */
|
|
14
|
+
export const TAGS_PER_LINK = 20;
|
|
15
|
+
/** The version this reader knows. */
|
|
16
|
+
export const READER_MAJOR = 1;
|
|
17
|
+
export const READER_MINOR = 0;
|
|
18
|
+
|
|
19
|
+
const AUTHOR_LEN = 120;
|
|
20
|
+
const SECTION_LEN = 120;
|
|
21
|
+
|
|
22
|
+
const ENVELOPE_KEYS = new Set(["$schema", "format", "app", "kind", "version", "generator", "id", "title", "description", "author", "license", "language", "updated", "homepage", "sections", "items"]);
|
|
23
|
+
const AUTHOR_KEYS = new Set(["name", "url"]);
|
|
24
|
+
const SECTION_KEYS = new Set(["name", "items"]);
|
|
25
|
+
const LINK_KEYS = new Set(["type", "url", "title", "description", "tags"]);
|
|
26
|
+
const FEED_KEYS = new Set(["type", "url", "site", "title"]);
|
|
27
|
+
|
|
28
|
+
class Refusal {
|
|
29
|
+
constructor(answer, why, app) {
|
|
30
|
+
this.answer = answer;
|
|
31
|
+
this.why = why;
|
|
32
|
+
this.app = app;
|
|
33
|
+
}
|
|
34
|
+
}
|
|
35
|
+
const refuse = (answer, why, app) => {
|
|
36
|
+
throw new Refusal(answer, why, app);
|
|
37
|
+
};
|
|
38
|
+
|
|
39
|
+
const own = (object, key) => (Object.prototype.hasOwnProperty.call(object, key) ? object[key] : undefined);
|
|
40
|
+
const isObject = (value) => value !== null && typeof value === "object" && !Array.isArray(value);
|
|
41
|
+
const string = (object, key) => {
|
|
42
|
+
const value = own(object, key);
|
|
43
|
+
return typeof value === "string" ? value : undefined;
|
|
44
|
+
};
|
|
45
|
+
const textOf = (object, key, max) => {
|
|
46
|
+
const value = string(object, key);
|
|
47
|
+
return value === undefined ? null : line(value, max);
|
|
48
|
+
};
|
|
49
|
+
|
|
50
|
+
/** Whether a text holds a surrogate without its pair. A loop, not a regex with a lookbehind, which Safari before 16.4 cannot parse. */
|
|
51
|
+
function hasLoneSurrogate(text) {
|
|
52
|
+
for (let i = 0; i < text.length; i++) {
|
|
53
|
+
const c = text.charCodeAt(i);
|
|
54
|
+
if (c >= 0xd800 && c <= 0xdbff) {
|
|
55
|
+
const next = text.charCodeAt(i + 1);
|
|
56
|
+
if (!(next >= 0xdc00 && next <= 0xdfff)) return true;
|
|
57
|
+
i++;
|
|
58
|
+
} else if (c >= 0xdc00 && c <= 0xdfff) {
|
|
59
|
+
return true;
|
|
60
|
+
}
|
|
61
|
+
}
|
|
62
|
+
return false;
|
|
63
|
+
}
|
|
64
|
+
|
|
65
|
+
/** Arrays and objects nest at most this deep, the file's own object being the first level. */
|
|
66
|
+
export const MAX_DEPTH = 127;
|
|
67
|
+
|
|
68
|
+
const isNumberChar = (c) => (c >= 0x30 && c <= 0x39) || c === 0x2d || c === 0x2b || c === 0x2e || c === 0x65 || c === 0x45;
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* Why a JSON text (one `JSON.parse` has accepted) is not one the format allows, or `undefined`
|
|
72
|
+
* when it is: a string (keys included) that is no Unicode text, a number out of a double's range,
|
|
73
|
+
* or arrays and objects nested more than {@link MAX_DEPTH} levels deep. The text is scanned rather
|
|
74
|
+
* than the parsed value, so a value a repeated key replaced is judged too: it still stands in the
|
|
75
|
+
* file, and a reader that parses every value (as Koona Pin's does) refuses it.
|
|
76
|
+
*/
|
|
77
|
+
function outOfBounds(text) {
|
|
78
|
+
let depth = 0;
|
|
79
|
+
for (let i = 0; i < text.length; i++) {
|
|
80
|
+
const c = text.charCodeAt(i);
|
|
81
|
+
if (c === 0x22) {
|
|
82
|
+
// A string, to its closing quote; escapes are decoded only when it has any.
|
|
83
|
+
let end = i + 1;
|
|
84
|
+
let escaped = false;
|
|
85
|
+
for (let k = text.charCodeAt(end); k !== 0x22; k = text.charCodeAt(end)) {
|
|
86
|
+
if (k === 0x5c) {
|
|
87
|
+
escaped = true;
|
|
88
|
+
end++;
|
|
89
|
+
}
|
|
90
|
+
end++;
|
|
91
|
+
}
|
|
92
|
+
const raw = text.slice(i, end + 1);
|
|
93
|
+
if (hasLoneSurrogate(escaped ? JSON.parse(raw) : raw)) return "a string holds a surrogate without its pair";
|
|
94
|
+
i = end;
|
|
95
|
+
} else if (c === 0x5b || c === 0x7b) {
|
|
96
|
+
if (++depth > MAX_DEPTH) return `arrays and objects nest more than ${MAX_DEPTH} levels deep`;
|
|
97
|
+
} else if (c === 0x5d || c === 0x7d) {
|
|
98
|
+
depth--;
|
|
99
|
+
} else if (c === 0x2d || (c >= 0x30 && c <= 0x39)) {
|
|
100
|
+
let end = i;
|
|
101
|
+
while (end < text.length && isNumberChar(text.charCodeAt(end))) end++;
|
|
102
|
+
if (!Number.isFinite(Number(text.slice(i, end)))) return "a number is out of the range of a double";
|
|
103
|
+
i = end - 1;
|
|
104
|
+
}
|
|
105
|
+
}
|
|
106
|
+
return undefined;
|
|
107
|
+
}
|
|
108
|
+
|
|
109
|
+
/** `[a-z][a-z0-9-]{0,31}`: `app` and `kind`. */
|
|
110
|
+
const isName = (s) => /^[a-z][a-z0-9-]{0,31}$/.test(s);
|
|
111
|
+
/** A plain decimal number: no sign, no leading zero (`0` alone is fine). */
|
|
112
|
+
const isPlain = (s) => /^(0|[1-9][0-9]*)$/.test(s);
|
|
113
|
+
|
|
114
|
+
/** `[MAJOR, MINOR]` of a version this reader opens; refuses any other. */
|
|
115
|
+
function version(raw) {
|
|
116
|
+
const dot = raw.indexOf(".");
|
|
117
|
+
if (dot < 0) refuse("not_a_list", `version ${JSON.stringify(raw)} is not MAJOR.MINOR`);
|
|
118
|
+
const major = raw.slice(0, dot);
|
|
119
|
+
const minor = raw.slice(dot + 1);
|
|
120
|
+
if (!isPlain(major) || !isPlain(minor)) refuse("not_a_list", `version ${JSON.stringify(raw)} is not MAJOR.MINOR`);
|
|
121
|
+
if (major === "0") refuse("not_a_list", "there is no MAJOR 0");
|
|
122
|
+
if (major !== String(READER_MAJOR)) refuse("needs_newer_app", `version ${raw}: MAJOR ${major} is newer than ${READER_MAJOR}`);
|
|
123
|
+
if (minor.length > 4) refuse("not_a_list", `version ${JSON.stringify(raw)}: version 1 has MINORs 0 to 9999`);
|
|
124
|
+
return [READER_MAJOR, Number(minor)];
|
|
125
|
+
}
|
|
126
|
+
|
|
127
|
+
/** `[a-z0-9][a-z0-9-]{0,63}`, the list's slug: at most 64 characters by its pattern. */
|
|
128
|
+
const slug = (raw) => (/^[a-z0-9][a-z0-9-]{0,63}$/.test(raw) ? raw : null);
|
|
129
|
+
|
|
130
|
+
/** A BCP 47 tag, loosely: 2–3 letters, then `-` parts of 2–8 letters or digits. */
|
|
131
|
+
function language(raw) {
|
|
132
|
+
const [first, ...parts] = raw.split("-");
|
|
133
|
+
const ok = /^[A-Za-z]{2,3}$/.test(first) && parts.every((p) => /^[A-Za-z0-9]{2,8}$/.test(p));
|
|
134
|
+
return ok ? raw : null;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/** `YYYY-MM-DD` exactly, a real date of the proleptic Gregorian calendar. */
|
|
138
|
+
function date(raw) {
|
|
139
|
+
const m = /^(\d{4})-(\d{2})-(\d{2})$/.exec(raw);
|
|
140
|
+
if (!m) return null;
|
|
141
|
+
const [year, month, day] = m.slice(1).map(Number);
|
|
142
|
+
const leap = (year % 4 === 0 && year % 100 !== 0) || year % 400 === 0;
|
|
143
|
+
const days = [31, leap ? 29 : 28, 31, 30, 31, 30, 31, 31, 30, 31, 30, 31][month - 1];
|
|
144
|
+
return days !== undefined && day >= 1 && day <= days ? raw : null;
|
|
145
|
+
}
|
|
146
|
+
|
|
147
|
+
const unknownKeys = (object, known) => Object.keys(object).filter((key) => !known.has(key));
|
|
148
|
+
|
|
149
|
+
const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: true });
|
|
150
|
+
|
|
151
|
+
/** The text of the input, refused when it is too big or not UTF-8. */
|
|
152
|
+
function textOfInput(input) {
|
|
153
|
+
if (typeof input === "string") {
|
|
154
|
+
if (utf8Length(input) > MAX_BYTES) refuse("too_big", `more than ${MAX_BYTES} bytes`);
|
|
155
|
+
return input;
|
|
156
|
+
}
|
|
157
|
+
let bytes;
|
|
158
|
+
const tag = Object.prototype.toString.call(input);
|
|
159
|
+
if (input instanceof Uint8Array) bytes = input;
|
|
160
|
+
else if (tag === "[object ArrayBuffer]" || tag === "[object SharedArrayBuffer]") bytes = new Uint8Array(input);
|
|
161
|
+
else if (ArrayBuffer.isView(input)) bytes = new Uint8Array(input.buffer, input.byteOffset, input.byteLength);
|
|
162
|
+
else throw new TypeError("read() takes a string, a Uint8Array, an ArrayBuffer or a SharedArrayBuffer");
|
|
163
|
+
if (bytes.length > MAX_BYTES) refuse("too_big", `${bytes.length} bytes, more than ${MAX_BYTES}`);
|
|
164
|
+
// TextDecoder refuses shared memory in browsers: decode a copy, which slice() makes unshared.
|
|
165
|
+
if (Object.prototype.toString.call(bytes.buffer) === "[object SharedArrayBuffer]") bytes = bytes.slice();
|
|
166
|
+
try {
|
|
167
|
+
return decoder.decode(bytes);
|
|
168
|
+
} catch {
|
|
169
|
+
return refuse("not_a_list", "the bytes are not UTF-8");
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
|
|
173
|
+
/**
|
|
174
|
+
* Reads a `.kpin` file: its text, or its bytes as they came (a file, a download). Every file gets
|
|
175
|
+
* one answer, and a list that is `ready` comes with what was read out of it.
|
|
176
|
+
* @param {string | Uint8Array | ArrayBuffer | SharedArrayBuffer | ArrayBufferView} input
|
|
177
|
+
* @returns {import("./index.js").Answer}
|
|
178
|
+
*/
|
|
179
|
+
export function read(input) {
|
|
180
|
+
try {
|
|
181
|
+
return { answer: "ready", list: readList(textOfInput(input)) };
|
|
182
|
+
} catch (error) {
|
|
183
|
+
if (!(error instanceof Refusal)) throw error;
|
|
184
|
+
const answer = { answer: error.answer, why: error.why };
|
|
185
|
+
if (error.answer === "other_app") answer.app = error.app;
|
|
186
|
+
return answer;
|
|
187
|
+
}
|
|
188
|
+
}
|
|
189
|
+
|
|
190
|
+
function readList(text) {
|
|
191
|
+
if (text.startsWith("\uFEFF")) text = text.slice(1);
|
|
192
|
+
let root;
|
|
193
|
+
try {
|
|
194
|
+
root = JSON.parse(text);
|
|
195
|
+
} catch {
|
|
196
|
+
refuse("not_a_list", "not JSON");
|
|
197
|
+
}
|
|
198
|
+
const out = outOfBounds(text);
|
|
199
|
+
if (out !== undefined) refuse("not_a_list", out);
|
|
200
|
+
if (!isObject(root)) refuse("not_a_list", "not a JSON object");
|
|
201
|
+
if (own(root, "format") !== "koona") refuse("not_a_list", 'format is not "koona"');
|
|
202
|
+
const app = string(root, "app");
|
|
203
|
+
if (app === undefined || !isName(app)) refuse("not_a_list", "app is missing or not a valid name");
|
|
204
|
+
if (app !== "pin") refuse("other_app", `the list is for app "${app}"`, app);
|
|
205
|
+
const kind = string(root, "kind");
|
|
206
|
+
if (kind === undefined || !isName(kind)) refuse("not_a_list", "kind is missing or not a valid name");
|
|
207
|
+
if (kind !== "list") refuse("needs_newer_app", `kind "${kind}" is not one this reader knows`);
|
|
208
|
+
const rawVersion = string(root, "version");
|
|
209
|
+
if (rawVersion === undefined) refuse("not_a_list", "version is missing or not a string");
|
|
210
|
+
const [major, minor] = version(rawVersion);
|
|
211
|
+
const newer = minor > READER_MINOR;
|
|
212
|
+
const title = textOf(root, "title", TITLE_LEN);
|
|
213
|
+
if (title === null) refuse("not_a_list", "title is missing, not a string or empty once cleaned");
|
|
214
|
+
|
|
215
|
+
// The structure: arrays of objects where the format has them.
|
|
216
|
+
const rawSections = own(root, "sections");
|
|
217
|
+
let sections = [];
|
|
218
|
+
if (Array.isArray(rawSections)) {
|
|
219
|
+
if (!rawSections.every(isObject)) refuse("not_a_list", "an entry of sections is not an object");
|
|
220
|
+
sections = rawSections;
|
|
221
|
+
} else if (rawSections !== undefined && rawSections !== null) {
|
|
222
|
+
refuse("not_a_list", "sections is neither an array nor null");
|
|
223
|
+
}
|
|
224
|
+
if (sections.length > MAX_SECTIONS) refuse("too_big", `${sections.length} entries of sections, more than ${MAX_SECTIONS}`);
|
|
225
|
+
const itemsOf = (object, where) => {
|
|
226
|
+
const items = own(object, "items");
|
|
227
|
+
if (items === undefined || items === null) return [];
|
|
228
|
+
if (!Array.isArray(items)) refuse("not_a_list", `${where} is neither an array nor null`);
|
|
229
|
+
return items;
|
|
230
|
+
};
|
|
231
|
+
const groups = sections.map((section, i) => ({ name: textOf(section, "name", SECTION_LEN), items: itemsOf(section, `sections[${i}].items`), at: `sections[${i}].items` }));
|
|
232
|
+
groups.push({ name: null, items: itemsOf(root, "items"), at: "items" });
|
|
233
|
+
const total = groups.reduce((sum, group) => sum + group.items.length, 0);
|
|
234
|
+
if (total > MAX_ITEMS) refuse("too_big", `${total} items, more than ${MAX_ITEMS}`);
|
|
235
|
+
if (total === 0) refuse("empty", "no items");
|
|
236
|
+
|
|
237
|
+
const rawAuthor = own(root, "author");
|
|
238
|
+
const author = isObject(rawAuthor) ? rawAuthor : undefined;
|
|
239
|
+
const authorName = author ? textOf(author, "name", AUTHOR_LEN) : null;
|
|
240
|
+
const authorUrl = author ? webAddress(own(author, "url")) : null;
|
|
241
|
+
const optional = (key, take) => {
|
|
242
|
+
const value = string(root, key);
|
|
243
|
+
return value === undefined ? null : take(value);
|
|
244
|
+
};
|
|
245
|
+
const list = {
|
|
246
|
+
title,
|
|
247
|
+
version: `${major}.${minor}`,
|
|
248
|
+
newer,
|
|
249
|
+
// Only a section with a name is one: the items of a nameless one are at the top level.
|
|
250
|
+
sections: groups.filter((group) => group.name !== null).length,
|
|
251
|
+
meta: {
|
|
252
|
+
description: optional("description", (s) => description(s, DESCRIPTION_LEN)),
|
|
253
|
+
author: authorName !== null || authorUrl !== null ? { name: authorName, url: authorUrl } : null,
|
|
254
|
+
license: textOf(root, "license", LICENSE_LEN),
|
|
255
|
+
language: optional("language", language),
|
|
256
|
+
updated: optional("updated", date),
|
|
257
|
+
homepage: webAddress(own(root, "homepage")),
|
|
258
|
+
id: optional("id", slug),
|
|
259
|
+
generator: textOf(root, "generator", GENERATOR_LEN),
|
|
260
|
+
},
|
|
261
|
+
counts: { links: 0, feeds: 0, repeated: 0, not_web: 0, invalid: 0, skipped_items: 0, skipped_details: 0 },
|
|
262
|
+
links: [],
|
|
263
|
+
feeds: [],
|
|
264
|
+
skipped: [],
|
|
265
|
+
};
|
|
266
|
+
const counts = list.counts;
|
|
267
|
+
const detail = (at, fields) => {
|
|
268
|
+
for (const field of fields) {
|
|
269
|
+
counts.skipped_details++;
|
|
270
|
+
list.skipped.push({ at, reason: "unknown_field", field });
|
|
271
|
+
}
|
|
272
|
+
};
|
|
273
|
+
if (newer) {
|
|
274
|
+
detail("", unknownKeys(root, ENVELOPE_KEYS));
|
|
275
|
+
if (author) detail("author", unknownKeys(author, AUTHOR_KEYS));
|
|
276
|
+
sections.forEach((section, i) => detail(`sections[${i}]`, unknownKeys(section, SECTION_KEYS)));
|
|
277
|
+
}
|
|
278
|
+
|
|
279
|
+
const linkAt = new Map();
|
|
280
|
+
const feedAt = new Set();
|
|
281
|
+
for (const group of groups) {
|
|
282
|
+
group.items.forEach((item, i) => {
|
|
283
|
+
const at = `${group.at}[${i}]`;
|
|
284
|
+
if (!isObject(item)) {
|
|
285
|
+
counts.skipped_items++;
|
|
286
|
+
list.skipped.push({ at, reason: "not_an_object" });
|
|
287
|
+
return;
|
|
288
|
+
}
|
|
289
|
+
const type = own(item, "type");
|
|
290
|
+
if (type === "link") {
|
|
291
|
+
if (newer) detail(at, unknownKeys(item, LINK_KEYS));
|
|
292
|
+
readLink(list, linkAt, item, group.name, at);
|
|
293
|
+
} else if (type === "feed") {
|
|
294
|
+
if (newer) detail(at, unknownKeys(item, FEED_KEYS));
|
|
295
|
+
readFeed(list, feedAt, item, group.name, at);
|
|
296
|
+
} else {
|
|
297
|
+
counts.skipped_items++;
|
|
298
|
+
list.skipped.push({ at, reason: "unknown_type", ...(typeof type === "string" ? { type } : {}) });
|
|
299
|
+
}
|
|
300
|
+
});
|
|
301
|
+
}
|
|
302
|
+
counts.links = list.links.length;
|
|
303
|
+
counts.feeds = list.feeds.length;
|
|
304
|
+
return list;
|
|
305
|
+
}
|
|
306
|
+
|
|
307
|
+
function skip(list, at, reason, url) {
|
|
308
|
+
list.counts[reason]++;
|
|
309
|
+
list.skipped.push({ at, reason, ...(url === undefined ? {} : { url }) });
|
|
310
|
+
}
|
|
311
|
+
|
|
312
|
+
function readLink(list, seen, item, section, at) {
|
|
313
|
+
const raw = string(item, "url");
|
|
314
|
+
if (raw === undefined) return skip(list, at, "invalid");
|
|
315
|
+
const taken = linkUrl(raw);
|
|
316
|
+
if ("skip" in taken) return skip(list, at, taken.skip, raw);
|
|
317
|
+
const url = taken.url;
|
|
318
|
+
const tags = [];
|
|
319
|
+
const rawTags = own(item, "tags");
|
|
320
|
+
if (Array.isArray(rawTags)) {
|
|
321
|
+
for (const raw of rawTags) {
|
|
322
|
+
const name = typeof raw === "string" ? tag(raw) : null;
|
|
323
|
+
if (name !== null && !tags.includes(name) && tags.length < TAGS_PER_LINK) tags.push(name);
|
|
324
|
+
}
|
|
325
|
+
}
|
|
326
|
+
// `linkUrl` admits only http(s) with a host, which always has a key.
|
|
327
|
+
const key = repeatKey(url) ?? url;
|
|
328
|
+
const first = seen.get(key);
|
|
329
|
+
if (first !== undefined) {
|
|
330
|
+
for (const name of tags) {
|
|
331
|
+
if (first.tags.length === TAGS_PER_LINK) break;
|
|
332
|
+
if (!first.tags.includes(name)) first.tags.push(name);
|
|
333
|
+
}
|
|
334
|
+
if (section !== null && !first.sections.includes(section)) first.sections.push(section);
|
|
335
|
+
return skip(list, at, "repeated", url);
|
|
336
|
+
}
|
|
337
|
+
const link = {
|
|
338
|
+
url,
|
|
339
|
+
title: textOf(item, "title", ITEM_TITLE_LEN),
|
|
340
|
+
description: (() => {
|
|
341
|
+
const value = string(item, "description");
|
|
342
|
+
return value === undefined ? null : description(value, DESCRIPTION_LEN);
|
|
343
|
+
})(),
|
|
344
|
+
tags,
|
|
345
|
+
sections: section === null ? [] : [section],
|
|
346
|
+
};
|
|
347
|
+
seen.set(key, link);
|
|
348
|
+
list.links.push(link);
|
|
349
|
+
}
|
|
350
|
+
|
|
351
|
+
function readFeed(list, seen, item, section, at) {
|
|
352
|
+
const raw = string(item, "url");
|
|
353
|
+
if (raw === undefined) return skip(list, at, "invalid");
|
|
354
|
+
const taken = feedUrl(raw);
|
|
355
|
+
if ("skip" in taken) return skip(list, at, taken.skip, raw);
|
|
356
|
+
if (seen.has(taken.url)) return skip(list, at, "repeated", taken.url);
|
|
357
|
+
seen.add(taken.url);
|
|
358
|
+
list.feeds.push({ url: taken.url, title: textOf(item, "title", ITEM_TITLE_LEN), site: webAddress(own(item, "site")), section });
|
|
359
|
+
}
|
package/src/text.js
ADDED
|
@@ -0,0 +1,256 @@
|
|
|
1
|
+
// Text as the spec's Text section cleans it: flags kept whole, invisible characters dropped,
|
|
2
|
+
// joiners judged by their neighbours, one-line fields and descriptions, the cut.
|
|
3
|
+
|
|
4
|
+
/** A title of the list, a section's name, `author.name`: 120 characters. */
|
|
5
|
+
export const TITLE_LEN = 120;
|
|
6
|
+
/** An item's title. */
|
|
7
|
+
export const ITEM_TITLE_LEN = 500;
|
|
8
|
+
/** A description of the list or of a link. */
|
|
9
|
+
export const DESCRIPTION_LEN = 2000;
|
|
10
|
+
/** A tag. */
|
|
11
|
+
export const TAG_LEN = 64;
|
|
12
|
+
export const LICENSE_LEN = 64;
|
|
13
|
+
export const GENERATOR_LEN = 80;
|
|
14
|
+
|
|
15
|
+
const ZWNJ = "\u200C";
|
|
16
|
+
const ZWJ = "\u200D";
|
|
17
|
+
|
|
18
|
+
const WHITE_SPACE = /\p{White_Space}/u;
|
|
19
|
+
const CONTROL = /\p{Cc}/u;
|
|
20
|
+
const PICTOGRAPHIC = /\p{Extended_Pictographic}/u;
|
|
21
|
+
const LEADING = /^\p{White_Space}+/u;
|
|
22
|
+
const TRAILING = /\p{White_Space}+$/u;
|
|
23
|
+
|
|
24
|
+
const isWhiteSpace = (c) => WHITE_SPACE.test(c);
|
|
25
|
+
const isControl = (c) => CONTROL.test(c);
|
|
26
|
+
|
|
27
|
+
/**
|
|
28
|
+
* The three subdivision flags Unicode recommends for general interchange (England, Scotland,
|
|
29
|
+
* Wales): U+1F3F4, the tags of `gbeng`, `gbsct` or `gbwls`, then CANCEL TAG. Only these keep their
|
|
30
|
+
* tag characters.
|
|
31
|
+
*/
|
|
32
|
+
const FLAGS = ["gbeng", "gbsct", "gbwls"].map((name) => [
|
|
33
|
+
"\u{1F3F4}",
|
|
34
|
+
...[...name].map((c) => String.fromCodePoint(0xe0000 + c.codePointAt(0))),
|
|
35
|
+
"\u{E007F}",
|
|
36
|
+
]);
|
|
37
|
+
|
|
38
|
+
/**
|
|
39
|
+
* The scripts where a joiner or non-joiner changes how letters are drawn: the joining scripts and
|
|
40
|
+
* the Brahmic ones of India and Sri Lanka. The Script property, not Script_Extensions.
|
|
41
|
+
*/
|
|
42
|
+
export const JOINING_SCRIPTS = Object.freeze([
|
|
43
|
+
"Arabic",
|
|
44
|
+
"Syriac",
|
|
45
|
+
"Nko",
|
|
46
|
+
"Mongolian",
|
|
47
|
+
"Mandaic",
|
|
48
|
+
"Manichaean",
|
|
49
|
+
"Adlam",
|
|
50
|
+
"Hanifi_Rohingya",
|
|
51
|
+
"Devanagari",
|
|
52
|
+
"Bengali",
|
|
53
|
+
"Gurmukhi",
|
|
54
|
+
"Gujarati",
|
|
55
|
+
"Oriya",
|
|
56
|
+
"Tamil",
|
|
57
|
+
"Telugu",
|
|
58
|
+
"Kannada",
|
|
59
|
+
"Malayalam",
|
|
60
|
+
"Sinhala",
|
|
61
|
+
]);
|
|
62
|
+
const SCRIPTS = JOINING_SCRIPTS.map((name) => new RegExp(`^\\p{Script=${name}}$`, "u"));
|
|
63
|
+
|
|
64
|
+
/**
|
|
65
|
+
* Whether one character (a code point) is one of the spec's invisible characters: U+00AD, U+061C,
|
|
66
|
+
* U+180E, U+200B–U+200F, U+202A–U+202E, U+2060–U+2064, U+2066–U+206F, U+FEFF, U+FFF9–U+FFFB,
|
|
67
|
+
* U+E0001 and U+E0020–U+E007F. Filter with this alone and the flags and joiners that are seen break:
|
|
68
|
+
* use {@link withoutInvisible}.
|
|
69
|
+
* @param {string} c
|
|
70
|
+
*/
|
|
71
|
+
export function isInvisible(c) {
|
|
72
|
+
const cp = c.codePointAt(0);
|
|
73
|
+
return (
|
|
74
|
+
cp === 0xad ||
|
|
75
|
+
cp === 0x61c ||
|
|
76
|
+
cp === 0x180e ||
|
|
77
|
+
(cp >= 0x200b && cp <= 0x200f) ||
|
|
78
|
+
(cp >= 0x202a && cp <= 0x202e) ||
|
|
79
|
+
(cp >= 0x2060 && cp <= 0x2064) ||
|
|
80
|
+
(cp >= 0x2066 && cp <= 0x206f) ||
|
|
81
|
+
cp === 0xfeff ||
|
|
82
|
+
(cp >= 0xfff9 && cp <= 0xfffb) ||
|
|
83
|
+
cp === 0xe0001 ||
|
|
84
|
+
(cp >= 0xe0020 && cp <= 0xe007f)
|
|
85
|
+
);
|
|
86
|
+
}
|
|
87
|
+
|
|
88
|
+
/**
|
|
89
|
+
* Whether a zero width joiner or non-joiner stays between `before` and `after`, judged once the
|
|
90
|
+
* other invisible characters and the controls that are not white space are gone: between two
|
|
91
|
+
* characters of one of the {@link JOINING_SCRIPTS}, or, a joiner, between two emoji.
|
|
92
|
+
* @param {string} joiner U+200D or U+200C
|
|
93
|
+
* @param {string | undefined} before
|
|
94
|
+
* @param {string | undefined} after
|
|
95
|
+
*/
|
|
96
|
+
export function joinerStays(joiner, before, after) {
|
|
97
|
+
if (before === undefined || after === undefined) return false;
|
|
98
|
+
const script = SCRIPTS.find((re) => re.test(before));
|
|
99
|
+
if (script && script.test(after)) return true;
|
|
100
|
+
const cp = before.codePointAt(0);
|
|
101
|
+
const joinsAfter = PICTOGRAPHIC.test(before) || cp === 0xfe0f || (cp >= 0x1f3fb && cp <= 0x1f3ff);
|
|
102
|
+
return joiner === ZWJ && joinsAfter && PICTOGRAPHIC.test(after);
|
|
103
|
+
}
|
|
104
|
+
|
|
105
|
+
/** Each character of `chars` and whether it is seen. */
|
|
106
|
+
function seenMarks(chars) {
|
|
107
|
+
if (!chars.some(isInvisible)) return chars.map((c) => [c, true]);
|
|
108
|
+
// The flags whole, everything but the joiners, then the joiners judged by what stands around them.
|
|
109
|
+
const marks = [];
|
|
110
|
+
for (let i = 0; i < chars.length; ) {
|
|
111
|
+
const flag = FLAGS.find((f) => f.every((c, k) => chars[i + k] === c));
|
|
112
|
+
if (flag) {
|
|
113
|
+
for (const c of flag) marks.push([c, true]);
|
|
114
|
+
i += flag.length;
|
|
115
|
+
continue;
|
|
116
|
+
}
|
|
117
|
+
const c = chars[i++];
|
|
118
|
+
marks.push([c, c === ZWJ || c === ZWNJ || !isInvisible(c)]);
|
|
119
|
+
}
|
|
120
|
+
// A white space control (a tab, a line break) stays a neighbour; other controls do not.
|
|
121
|
+
const kept = [];
|
|
122
|
+
marks.forEach(([c, seen], i) => {
|
|
123
|
+
if (seen && !(isControl(c) && !isWhiteSpace(c))) kept.push(i);
|
|
124
|
+
});
|
|
125
|
+
const judged = [];
|
|
126
|
+
kept.forEach((i, at) => {
|
|
127
|
+
const c = marks[i][0];
|
|
128
|
+
if (c !== ZWJ && c !== ZWNJ) return;
|
|
129
|
+
const before = at > 0 ? marks[kept[at - 1]][0] : undefined;
|
|
130
|
+
const after = at + 1 < kept.length ? marks[kept[at + 1]][0] : undefined;
|
|
131
|
+
judged.push([i, joinerStays(c, before, after)]);
|
|
132
|
+
});
|
|
133
|
+
for (const [i, stays] of judged) marks[i][1] = stays;
|
|
134
|
+
return marks;
|
|
135
|
+
}
|
|
136
|
+
|
|
137
|
+
/**
|
|
138
|
+
* The text without its invisible characters, except those that are seen: the tags of the three
|
|
139
|
+
* subdivision flags, kept whole, and a joiner or non-joiner where it changes what is drawn.
|
|
140
|
+
* @param {string} raw
|
|
141
|
+
*/
|
|
142
|
+
export function withoutInvisible(raw) {
|
|
143
|
+
return seenOnly(Array.from(raw), raw);
|
|
144
|
+
}
|
|
145
|
+
|
|
146
|
+
/** {@link withoutInvisible} of text already split into code points; `raw` is that text, if known. */
|
|
147
|
+
function seenOnly(chars, raw = undefined) {
|
|
148
|
+
if (!chars.some(isInvisible)) return raw ?? chars.join("");
|
|
149
|
+
return seenMarks(chars)
|
|
150
|
+
.filter(([, seen]) => seen)
|
|
151
|
+
.map(([c]) => c)
|
|
152
|
+
.join("");
|
|
153
|
+
}
|
|
154
|
+
|
|
155
|
+
/** Text that the marks keep whole: nothing to drop, single plain spaces between words. */
|
|
156
|
+
function isALine(chars) {
|
|
157
|
+
let spaceBefore = true;
|
|
158
|
+
for (const c of chars) {
|
|
159
|
+
if (c === " ") {
|
|
160
|
+
if (spaceBefore) return false;
|
|
161
|
+
spaceBefore = true;
|
|
162
|
+
} else if (isWhiteSpace(c) || isControl(c) || isInvisible(c)) {
|
|
163
|
+
return false;
|
|
164
|
+
} else {
|
|
165
|
+
spaceBefore = false;
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
return !spaceBefore || chars.length === 0;
|
|
169
|
+
}
|
|
170
|
+
|
|
171
|
+
/**
|
|
172
|
+
* At most `max` characters, the end trimmed; empty is none. A cut through a flag leaves its tags
|
|
173
|
+
* without their end, and a cut right after a joiner leaves it with nothing after it: they go too.
|
|
174
|
+
*/
|
|
175
|
+
function capped(text, max, chars = Array.from(text)) {
|
|
176
|
+
let cut = chars.length > max ? seenOnly(chars.slice(0, max)) : text;
|
|
177
|
+
cut = cut.replace(TRAILING, "");
|
|
178
|
+
return cut === "" ? null : cut;
|
|
179
|
+
}
|
|
180
|
+
|
|
181
|
+
/**
|
|
182
|
+
* What a one-line field becomes: a title, a section's name, `author.name`, `license`, `generator`.
|
|
183
|
+
* White space becomes one space between words, controls and invisible characters go, at most
|
|
184
|
+
* `max` characters. `null` when nothing is left.
|
|
185
|
+
* @param {string} raw
|
|
186
|
+
* @param {number} max
|
|
187
|
+
* @returns {string | null}
|
|
188
|
+
*/
|
|
189
|
+
export function line(raw, max) {
|
|
190
|
+
const chars = Array.from(raw);
|
|
191
|
+
if (isALine(chars)) return capped(raw, max, chars);
|
|
192
|
+
const marks = seenMarks(chars).map(([c, seen]) => [c, seen ? "kept" : "dropped"]);
|
|
193
|
+
// Between two words one character of the white space stays: the first plain space, or else the
|
|
194
|
+
// first of them, as a plain space.
|
|
195
|
+
let run = [];
|
|
196
|
+
let wordBefore = false;
|
|
197
|
+
for (let i = 0; i < marks.length; i++) {
|
|
198
|
+
const [c, mark] = marks[i];
|
|
199
|
+
if (mark === "dropped") continue;
|
|
200
|
+
if (isWhiteSpace(c)) {
|
|
201
|
+
marks[i][1] = "dropped";
|
|
202
|
+
run.push(i);
|
|
203
|
+
} else if (isControl(c)) {
|
|
204
|
+
marks[i][1] = "dropped";
|
|
205
|
+
} else {
|
|
206
|
+
if (wordBefore && run.length > 0) {
|
|
207
|
+
const space = run.find((j) => marks[j][0] === " ");
|
|
208
|
+
if (space !== undefined) marks[space][1] = "kept";
|
|
209
|
+
else marks[run[0]][1] = "space";
|
|
210
|
+
}
|
|
211
|
+
run = [];
|
|
212
|
+
wordBefore = true;
|
|
213
|
+
}
|
|
214
|
+
}
|
|
215
|
+
const kept = marks.filter(([, mark]) => mark !== "dropped").map(([c, mark]) => (mark === "space" ? " " : c));
|
|
216
|
+
return capped(kept.join(""), max, kept);
|
|
217
|
+
}
|
|
218
|
+
|
|
219
|
+
/**
|
|
220
|
+
* What a description becomes: as {@link line}, but its line breaks stay. `\r\n` becomes `\n`,
|
|
221
|
+
* every other control goes, the ends are trimmed. `null` when nothing is left.
|
|
222
|
+
* @param {string} raw
|
|
223
|
+
* @param {number} [max]
|
|
224
|
+
* @returns {string | null}
|
|
225
|
+
*/
|
|
226
|
+
export function description(raw, max = DESCRIPTION_LEN) {
|
|
227
|
+
// Split into code points once: cleaned, controls dropped and the ends trimmed on the array.
|
|
228
|
+
const chars = Array.from(raw.replaceAll("\r\n", "\n"));
|
|
229
|
+
const seen = chars.some(isInvisible) ? seenMarks(chars).filter(([, s]) => s).map(([c]) => c) : chars;
|
|
230
|
+
const kept = seen.filter((c) => c === "\n" || !isControl(c));
|
|
231
|
+
const trimmed = trimChars(kept);
|
|
232
|
+
return capped(trimmed.join(""), max, trimmed);
|
|
233
|
+
}
|
|
234
|
+
|
|
235
|
+
/**
|
|
236
|
+
* A tag: lowercased (the default Unicode lowercase), one line, at most 64 characters.
|
|
237
|
+
* @param {string} raw
|
|
238
|
+
* @returns {string | null}
|
|
239
|
+
*/
|
|
240
|
+
export function tag(raw) {
|
|
241
|
+
return line(raw.toLowerCase(), TAG_LEN);
|
|
242
|
+
}
|
|
243
|
+
|
|
244
|
+
/** Trims Unicode White_Space off both ends (not U+FEFF, which `String.prototype.trim` takes too). */
|
|
245
|
+
export function trimWhiteSpace(text) {
|
|
246
|
+
return text.replace(LEADING, "").replace(TRAILING, "");
|
|
247
|
+
}
|
|
248
|
+
|
|
249
|
+
/** {@link trimWhiteSpace} of text already split into code points: the same rule, on the array. */
|
|
250
|
+
function trimChars(chars) {
|
|
251
|
+
let start = 0;
|
|
252
|
+
let end = chars.length;
|
|
253
|
+
while (start < end && isWhiteSpace(chars[start])) start++;
|
|
254
|
+
while (end > start && isWhiteSpace(chars[end - 1])) end--;
|
|
255
|
+
return chars.slice(start, end);
|
|
256
|
+
}
|