Port helpers.js to TypeScript

This commit is contained in:
Hornwitser committed 2023-08-03 15:03:52 +02:00
1 parent 74e9ed8257
commit dedb42447c
1 file changed
+80 -74
@@ -2,7 +2,6 @@
* Collection of small utilites that are useful in multiple places. * Collection of small utilites that are useful in multiple places.
* @module lib/helpers * @module lib/helpers
*/ */
"use strict";
/** /**
* Return a string describing the type of the value passed * Return a string describing the type of the value passed
@@ -10,11 +9,10 @@
* Works the same as typeof, excpet that null and array types get their * Works the same as typeof, excpet that null and array types get their
* own string. * own string.
* *
* @param {*} value - value to return the type of. * @param value - value to return the type of.
* @returns {string} basic type of the value passed. * @returns basic type of the value passed.
* @static
*/ */
function basicType(value) { export function basicType(value: unknown) {
if (value === null) { return "null"; } if (value === null) { return "null"; }
if (value instanceof Array) { return "array"; } if (value instanceof Array) { return "array"; }
return typeof value; return typeof value;
@@ -24,10 +22,9 @@ function basicType(value) {
/** /**
* Asynchronously wait for the given duration * Asynchronously wait for the given duration
* *
* @param {number} duration - Time to wait for in milliseconds. * @param duration - Time to wait for in milliseconds.
* @static
*/ */
async function wait(duration) { export async function wait(duration: number) {
await new Promise(resolve => { setTimeout(resolve, duration); }); await new Promise(resolve => { setTimeout(resolve, duration); });
} }
@@ -38,10 +35,9 @@ async function wait(duration) {
* @param {Promise} promise - Promise to wait for. * @param {Promise} promise - Promise to wait for.
* @param {number} time - Maximum time im milliseconds to wait for. * @param {number} time - Maximum time im milliseconds to wait for.
* @param {*=} timeoutResult - Value to return if the operation timed out. * @param {*=} timeoutResult - Value to return if the operation timed out.
* @static
*/ */
async function timeout(promise, time, timeoutResult) { export async function timeout<T>(promise: Promise<T>, time: number, timeoutResult: T) {
let timer; let timer: ReturnType<typeof setTimeout>;
try { try {
return await Promise.race([ return await Promise.race([
promise, promise,
@@ -62,18 +58,17 @@ async function timeout(promise, time, timeoutResult) {
* Reads the stream given asynchronously until the end is reached and * Reads the stream given asynchronously until the end is reached and
* returns all the data which was read from the stream. * returns all the data which was read from the stream.
* *
* @param {Readable} stream - byte stream to read to the end. * @param stream - byte stream to read to the end.
* @returns {Promise<Buffer>} content of the stream. * @returns content of the stream.
* @static
*/ */
async function readStream(stream) { export async function readStream(stream: NodeJS.ReadableStream & { isTTY?: boolean }) {
let chunks = []; let chunks: Buffer[] = [];
for await (let chunk of stream) { for await (let chunk of stream) {
// Support using ^Z to end input on Windows // Support using ^Z to end input on Windows
if (process.platform === "win32" && stream.isTTY && chunk.toString() === "\x1a\r\n") { if (process.platform === "win32" && stream.isTTY && chunk.toString() === "\x1a\r\n") {
break; break;
} }
chunks.push(chunk); chunks.push(chunk as Buffer);
} }
return Buffer.concat(chunks); return Buffer.concat(chunks);
} }
@@ -87,11 +82,10 @@ async function readStream(stream) {
* *
* See https://stackoverflow.com/a/9310752 * See https://stackoverflow.com/a/9310752
* *
* @param {string} text - Text to escape RegExp meta chars in. * @param text - Text to escape RegExp meta chars in.
* @returns {string} escaped text. * @returns escaped text.
* @static
*/ */
function escapeRegExp(text) { export function escapeRegExp(text: string) {
return text.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, "\\$&"); return text.replace(/[-[\]{}()*+?.,\\^$|#\s]/g, "\\$&");
} }
@@ -99,11 +93,10 @@ function escapeRegExp(text) {
* Format byte count for human readable display * Format byte count for human readable display
* *
* Shortens a large number of bytes using the kB/MB/GB/TB prefixes. * Shortens a large number of bytes using the kB/MB/GB/TB prefixes.
* @param {number} bytes - Count of bytes to format. * @param bytes - Count of bytes to format.
* @returns {string} formatted text. * @returns formatted text.
* @static
*/ */
function formatBytes(bytes) { export function formatBytes(bytes: number) {
if (bytes === 0) { if (bytes === 0) {
return "0\u{A0}Bytes"; // No-break space return "0\u{A0}Bytes"; // No-break space
} }
@@ -114,7 +107,7 @@ function formatBytes(bytes) {
return (power > 0 ? (bytes / factor ** power).toFixed(2) : bytes) + units[power]; return (power > 0 ? (bytes / factor ** power).toFixed(2) : bytes) + units[power];
} }
function parseSearchIdentifier(pos, input) { function parseSearchIdentifier(pos: number, input: string): [number, string] {
// character = ? all characters excluding space : " ? // character = ? all characters excluding space : " ?
// identifier = 1*character // identifier = 1*character
let startPos = pos; let startPos = pos;
@@ -124,15 +117,14 @@ function parseSearchIdentifier(pos, input) {
return [pos, input.slice(startPos, pos)]; return [pos, input.slice(startPos, pos)];
} }
function parseSearchWord(pos, input) { function parseSearchWord(pos: number, input: string): [number, ParsedWord] {
// non quote character = ? all characters excluding " ? // non quote character = ? all characters excluding " ?
// word op = "-" // word op = "-"
// word = [ word op ], ( identifier | '"', *non quote character, '"' ) // word = [ word op ], ( identifier | '"', *non quote character, '"' )
let word = { let exclude = false;
type: "word", let value: string;
};
if (input.charAt(pos) === "-") { if (input.charAt(pos) === "-") {
word.exclude = true; exclude = true;
pos += 1; pos += 1;
} }
if (input.charAt(pos) === '"') { if (input.charAt(pos) === '"') {
@@ -146,21 +138,33 @@ function parseSearchWord(pos, input) {
if (input.charAt(pos) === '"') { if (input.charAt(pos) === '"') {
pos += 1; pos += 1;
} }
word.value = input.slice(startPos, endPos); value = input.slice(startPos, endPos);
} else { } else {
([pos, word.value] = parseSearchIdentifier(pos, input)); ([pos, value] = parseSearchIdentifier(pos, input));
}
let word: ParsedWord = {
type: "word",
value,
};
if (exclude) {
word.exclude = true;
} }
return [pos, word]; return [pos, word];
} }
function parseSearchTerm(pos, input, attributes, issues) { function parseSearchTerm(
pos: number,
input: string,
attributes: Record<string, string>,
issues: Array<string>
): [number, ParsedTerm] {
// attribute = identifier, ':', word // attribute = identifier, ':', word
// term = word | attribute // term = word | attribute
let term; let term: ParsedTerm;
if (["-", '"'].includes(input.charAt(pos))) { if (["-", '"'].includes(input.charAt(pos))) {
([pos, term] = parseSearchWord(pos, input)); ([pos, term] = parseSearchWord(pos, input));
} else { } else {
let identifier; let identifier: string;
([pos, identifier] = parseSearchIdentifier(pos, input)); ([pos, identifier] = parseSearchIdentifier(pos, input));
if (input.charAt(pos) === ":") { if (input.charAt(pos) === ":") {
pos += 1; pos += 1;
@@ -168,7 +172,7 @@ function parseSearchTerm(pos, input, attributes, issues) {
if (!Object.prototype.hasOwnProperty.call(attributes, identifier)) { if (!Object.prototype.hasOwnProperty.call(attributes, identifier)) {
issues.push(`Unregonized attribute "${identifier}", use quotes to escape colons`); issues.push(`Unregonized attribute "${identifier}", use quotes to escape colons`);
} else if (attributes[identifier] === "word") { } else if (attributes[identifier] === "word") {
let value; let value: ParsedWord;
([pos, value] = parseSearchWord(pos, input)); ([pos, value] = parseSearchWord(pos, input));
term = { type: "attribute", name: identifier, value }; term = { type: "attribute", name: identifier, value };
} else { } else {
@@ -188,17 +192,17 @@ function parseSearchTerm(pos, input, attributes, issues) {
* of the passed text snippets. If the word mode is exclude then returns * of the passed text snippets. If the word mode is exclude then returns
* true if none of the passed text snippets match. * true if none of the passed text snippets match.
* *
* @param {lib/helpers.ParsedTerm} word - Word to match. * @param word - Word to match.
* @param {...string} texts - Text to match word in. * @param texts - Text to match word in.
* @returns {boolean} true if the word matches. * @returns true if the word matches.
*/ */
function wordMatches(word, ...texts) { export function wordMatches(word: ParsedTerm, ...texts: string[]) {
if (word.type !== "word") { if (word.type !== "word") {
throw Error("wordMatches: parameter is not a word"); throw Error("wordMatches: parameter is not a word");
} }
let matches = false; let matches = false;
for (let text of texts) { for (let text of texts) {
if (text.includes(word.value)) { if (text.includes(word.value as string)) {
matches = true; matches = true;
break; break;
} }
@@ -209,23 +213,35 @@ function wordMatches(word, ...texts) {
return matches; return matches;
} }
/** export interface ParsedAttribute {
* @typedef {object} ParsedTerm /** Type of term, either attribute or word. */
* @property {string} type - Type of term, either attribute or word. type: "attribute"
* @property {string=} name - attribute only: Name of attribute. /** Name of attribute. */
* @property {boolean=} exclude - word only: exclude results with this word. name: string;
* @property {string | ParsedTerm} value - /** Parsed value of this attribute. */
* Parsed value of this term. Is a string if type is word, and a value: ParsedWord;
* ParsedTerm if type is attribute. }
*/
export interface ParsedWord {
/** Type of term, either attribute or word. */
type: "word";
/** Exclude results with this word. */
exclude?: boolean;
/** Parsed text of this word. */
value: string;
}
export type ParsedTerm = ParsedAttribute | ParsedWord;
/** /**
* @typedef {object} ParsedSearch * Result from {@link parseSearchString}.
* @property {Array<ParsedTerm>} terms -
* Parsed result of search terms.
* @property {Array<string>} issues -
* Issues detected while parsing the seach string.
*/ */
export interface ParsedSearch {
/** Parsed result of search terms. */
terms: Array<ParsedTerm>;
/** Issues detected while parsing the seach string. */
issues: Array<string>;
};
/** /**
* Parse a search string with optional attributes * Parse a search string with optional attributes
@@ -244,14 +260,16 @@ function wordMatches(word, ...texts) {
* The issues should be shown to the end user so that they can correct their * The issues should be shown to the end user so that they can correct their
* search. * search.
* *
* @param {string} input - Search expression to parse. * @param input - Search expression to parse.
* @param {Object<string, string>} attributes - * @param attributes -
* Recognized attributes and their format. Currently only word is * Recognized attributes and their format. Currently only word is
* supported. * supported.
* @returns {ParsedSearch} parsed terms of the search. * @returns parsed terms of the search.
* @static
*/ */
function parseSearchString(input, attributes = {}) { export function parseSearchString(
input: string,
attributes: Record<string, string> = {}
): ParsedSearch {
// whitespace = 1*" " // whitespace = 1*" "
// search = [ term, *( [ whitespace ], term ) ] // search = [ term, *( [ whitespace ], term ) ]
input = input.trim(); input = input.trim();
@@ -261,7 +279,7 @@ function parseSearchString(input, attributes = {}) {
}; };
let pos = 0; let pos = 0;
while (pos < input.length) { while (pos < input.length) {
let term; let term: ParsedTerm;
([pos, term] = parseSearchTerm(pos, input, attributes, parsed.issues)); ([pos, term] = parseSearchTerm(pos, input, attributes, parsed.issues));
if (term) { if (term) {
parsed.terms.push(term); parsed.terms.push(term);
@@ -276,15 +294,3 @@ function parseSearchString(input, attributes = {}) {
} }
return parsed; return parsed;
} }
module.exports = {
basicType,
wait,
timeout,
readStream,
escapeRegExp,
formatBytes,
wordMatches,
parseSearchString,
};