From 09be09750379fdd8e6fbecd0310a3e8d2b41f1ed Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?S=C3=B6ren=20Meier?= Date: Mon, 5 Feb 2024 01:31:34 +0100 Subject: [PATCH] add more types --- .vscode/settings.json | 4 + src/api/Api.d.ts | 78 +++++++++++++++++ src/api/ApiError.d.ts | 47 +++++++++++ src/sync/NonConcurrent.d.ts | 17 ++++ src/sync/NonConcurrent.js | 9 +- src/time/Date.d.ts | 116 +++++++++++++++++++++++++ src/time/DateTime.d.ts | 164 ++++++++++++++++++++++++++++++++++++ src/time/DateTimeRange.d.ts | 36 ++++++++ src/time/Duration.d.ts | 39 +++++++++ 9 files changed, 509 insertions(+), 1 deletion(-) create mode 100644 .vscode/settings.json create mode 100644 src/api/Api.d.ts create mode 100644 src/api/ApiError.d.ts create mode 100644 src/sync/NonConcurrent.d.ts create mode 100644 src/time/Date.d.ts create mode 100644 src/time/DateTime.d.ts create mode 100644 src/time/DateTimeRange.d.ts create mode 100644 src/time/Duration.d.ts diff --git a/.vscode/settings.json b/.vscode/settings.json new file mode 100644 index 0000000..fe95ac3 --- /dev/null +++ b/.vscode/settings.json @@ -0,0 +1,4 @@ +{ + "editor.formatOnPaste": true, + "editor.formatOnSave": true +} \ No newline at end of file diff --git a/src/api/Api.d.ts b/src/api/Api.d.ts new file mode 100644 index 0000000..4c0b04b --- /dev/null +++ b/src/api/Api.d.ts @@ -0,0 +1,78 @@ +import ApiError from './ApiError'; + +/** + * Api class to handle requests to a server + */ +export default class Api { + /** + * get or set the api address + */ + addr: string; + + /** + * Creates a new Api instance + */ + constructor(addr?: string); + + /** + * Prepares a json object to be sent as a header + */ + static jsonHeader(data: object): string; + + /** + * Send a request to the server + * + * @param {string} method - The method of the request + * @param {string} path - The path of the request + * @param {object|null} data - The data to be sent + * @param {object} headers - The headers to be sent + * @param {object} opts - The additional options to be sent to fetch + * + * @returns The response of the request + * + * @throws {ApiError} - If the request fails + */ + request( + method: string, + path: string, + data?: object | null, + headers?: object, + opts?: object, + ): Promise; + + /** + * Send a request to the server with a file + * + * @param {string} method - The method of the request + * @param {string} path - The path of the request + * @param {File} file - The file to be sent + * @param {function|null} progress - The progress callback + * @param {object} headers - The headers to be sent + * + * @throws {ApiError} - If the request fails + */ + requestWithFile( + method: string, + path: string, + file: File, + progress: ((event: ProgressEvent) => void) | null, + headers: object, + ): Promise; + + /** + * Send a request to the server with a timeout + * + * @param {string} method - The method of the request + * @param {string} path - The path of the request + * @param {object|null} data - The data to be sent + * @param {object} headers - The headers to be sent + * @param {number} timeout - The timeout of the request if the value is 0 there is no timeout + */ + requestTimeout( + method: string, + path: string, + data?: object | null, + headers?: object, + timeout?: number, + ): Promise; +} diff --git a/src/api/ApiError.d.ts b/src/api/ApiError.d.ts new file mode 100644 index 0000000..aedc2c0 --- /dev/null +++ b/src/api/ApiError.d.ts @@ -0,0 +1,47 @@ +export default class ApiError { + /** + * The kind of error + */ + kind: string; + + /** + * The data associated with this error + * + * should provide a toString method + */ + data: any; + + /** + * Creates a new ApiError + */ + constructor(kind: string, data: any); + + /** + * The message of the error + * + * @returns {string} + */ + get msg(): string; + + /** + * Creates a new ApiError with the kind 'OTHER' + */ + static newOther(data: any): ApiError; + + /** + * Creates a new ApiError with the kind 'SESSION_NOT_FOUND' + */ + static newSessionError(): ApiError; + + /** + * Returns a string representation of the error + */ + toString(): string; +} + +/** + * Returns whether the value is an ApiError object + * + * @returns {boolean} + */ +export function isApiErrorObject(value: any): boolean; diff --git a/src/sync/NonConcurrent.d.ts b/src/sync/NonConcurrent.d.ts new file mode 100644 index 0000000..b901ef1 --- /dev/null +++ b/src/sync/NonConcurrent.d.ts @@ -0,0 +1,17 @@ +export type NonConcurrentReady = { + ready: () => void; +}; + +export default class NonConcurrent { + /** + * Creates a new NonConcurrent + */ + constructor(); + + /** + * Waits until any other non-concurrent requests is done then waits until you call ready + * + * returns an object where you need to call ready once done + */ + start(): Promise; +} diff --git a/src/sync/NonConcurrent.js b/src/sync/NonConcurrent.js index 345ceef..848da96 100644 --- a/src/sync/NonConcurrent.js +++ b/src/sync/NonConcurrent.js @@ -1,11 +1,18 @@ /// synchronisation point export default class NonConcurrent { + /** + * Creates a new NonConcurrent + */ constructor() { this.listeners = []; this.running = false; } - // returns an object where you need to call ready once done + /** + * Waits until any other non-concurrent requests is done then waits until you call ready + * + * returns an object where you need to call ready once done + */ async start() { if (this.running) { await new Promise(resolve => { diff --git a/src/time/Date.d.ts b/src/time/Date.d.ts new file mode 100644 index 0000000..b95c7e1 --- /dev/null +++ b/src/time/Date.d.ts @@ -0,0 +1,116 @@ +export default class Date { + /** + * Tries to creates a new Date instance + */ + static parse(val: any): Date; + + /** + * Create a new Date instance + * @constructor + * @param {Date|string|number} date - The date value. Default is + * current date. + * If it's a string or number, convert it to a date. + * @throws {Error} Will throw an error if date is an invalid Date. + */ + constructor(date?: Date | string | number); + + /** + * Check if the date represented by this instance is today + * @returns {boolean} True if the date represented by this instance is + * today, otherwise false + */ + isToday(): boolean; + + /** + * Get the year from the date ex: 2023 + * @returns {number} The year in which the date occurs + */ + get year(): number; + + /** + * Get the month from the date (0 indexed) + * @returns {number} The month in which the date occurs, zero-indexed + */ + get month(): number; + + /** + * Get the date (day of the month 1-31) + * @returns {number} The day of the month on which the date occurs + */ + get date(): number; + + /** + * Get the week of the year + * @returns {number} The week of the year in which the date occurs + */ + get week(): number; + + /** + * Get the day of the week (0 indexed) + * @returns {number} The day of the week on which the date occurs, + * zero-indexed with 0 for Sunday + */ + get day(): number; + + /** + * Get the day of the week (1 indexed with Monday as 1) + * @returns {number} The day of the week on which the date occurs, with 1 + * for Monday and 7 for Sunday + */ + get dayMoToSu(): number; + + /** + * Get the number of milliseconds since 1 January 1970 00:00:00 UTC + * @returns {number} The number of milliseconds since the Unix Epoch + */ + get time(): number; + + /** + * Create a new Date object representing the same day + * @returns {Date} A new Date object with the same year, month, and + * date + */ + clone(): Date; + + /** + * Get the name of the month in a given language + * @param {string|null} lang - The language to get the month name in + * @returns {string|null} The name of the month in the given language, + * or null if the language is not provided + */ + toStrMonth(lang?: string | null): string | null; + + /** + * Get the name of the day in a given language + * @param {string|null} lang - The language to get the day name in + * @returns {string|null} The name of the day in the given language, + * or null if the language is not provided + */ + toStrDay(lang?: string | null): string | null; + + /** + * Get the first letter of the day in a given language, in uppercase + * @param {string|null} lang - The language to get the day name in + * @returns {string|null} The first letter of the day in the given + * language, or null if the language is not provided + */ + toStrDayLetter(lang?: string | null): string | null; + + /** + * Get a short representation of the date (dd.mm) + * @returns {string} A string representing the date in the form dd.mm + */ + toStrShort(): string; + + /** + * Get a representation of the date (dd.mm.yyyy) + * @returns {string} A string representing the date in the form dd.mm.yyyy + */ + toStr(): string; + + /** + * Get a representation of the date suitable for a browser (yyyy-mm-dd) + * @returns {string} A string representing the date in the form yyyy-mm-dd + */ + toBrowserDate(): string; +} diff --git a/src/time/DateTime.d.ts b/src/time/DateTime.d.ts new file mode 100644 index 0000000..a341586 --- /dev/null +++ b/src/time/DateTime.d.ts @@ -0,0 +1,164 @@ +export default class DateTime { + /** + * Tries to creates a new DateTime instance + */ + static parse(val: any): DateTime; + + /** + * Create a new DateTime instance + * @constructor + * @param {Date|DateTime|string|number} date - The date value. Default is + * current date/time. + * If it's a string or number, convert it to a date. + * @throws {Error} Will throw an error if date is an invalid Date. + */ + constructor(date?: Date | DateTime | string | number); + + /** + * Create a new DateTime instance representing today's date + * @static + * @returns {DateTime} A DateTime object representing today's date with the + * time set to 0 + */ + static today(): DateTime; + + /** + * Check if the date represented by this instance is today + * @returns {boolean} True if the date represented by this instance is + * today, otherwise false + */ + isToday(): boolean; + + /** + * Get the year from the date ex: 2023 + * @returns {number} The year in which the date occurs + */ + get year(): number; + + /** + * Get the month from the date (0 indexed) + * @returns {number} The month in which the date occurs, zero-indexed + */ + get month(): number; + + /** + * Get the date (day of the month 1-31) + * @returns {number} The day of the month on which the date occurs + */ + get date(): number; + + /** + * Get the week of the year + * @returns {number} The week of the year in which the date occurs + */ + get week(): number; + + /** + * Get the day of the week (0 indexed) + * @returns {number} The day of the week on which the date occurs, + * zero-indexed with 0 for Sunday + */ + get day(): number; + + /** + * Get the day of the week (1 indexed with Monday as 1) + * @returns {number} The day of the week on which the date occurs, with 1 + * for Monday and 7 for Sunday + */ + get dayMoToSu(): number; + + /** + * Get the hours part of the date + * @returns {number} The hour of the day on which the date occurs, from 0 + * to 23 + */ + get hours(): number; + + /** + * Get the minutes part of the date + * @returns {number} The minute of the hour on which the date occurs, from + * 0 to 59 + */ + get minutes(): number; + + /** + * Get the seconds part of the date + * @returns {number} The second of the minute on which the date occurs, + * from 0 to 59 + */ + get seconds(): number; + + /** + * Get the milliseconds part of the date + * @returns {number} The milliseconds of the second on which the date + * occurs, from 0 to 999 + */ + get millis(): number; + + /** + * Get the number of milliseconds since 1 January 1970 00:00:00 UTC + * @returns {number} The number of milliseconds since the Unix Epoch + */ + get time(): number; + + /** + * Create a new DateTime object representing the same day + * @returns {DateTime} A new DateTime object with the same year, month, and + * date + */ + cloneDay(): DateTime; + + /** + * Get the name of the month in a given language + * @param {string|null} lang - The language to get the month name in + * @returns {string|null} The name of the month in the given language, + * or null if the language is not provided + */ + toStrMonth(lang?: string | null): string | null; + + /** + * Get the name of the day in a given language + * @param {string|null} lang - The language to get the day name in + * @returns {string|null} The name of the day in the given language, + * or null if the language is not provided + */ + toStrDay(lang?: string | null): string | null; + + /** + * Get the first letter of the day in a given language, in uppercase + * @param {string|null} lang - The language to get the day name in + * @returns {string|null} The first letter of the day in the given + * language, or null if the language is not provided + */ + toStrDayLetter(lang?: string | null): string | null; + + /** + * Get a short representation of the date (dd.mm) + * @returns {string} A string representing the date in the form dd.mm + */ + toStrShortDate(): string; + + /** + * Get a representation of the date (dd.mm.yyyy) + * @returns {string} A string representing the date in the form dd.mm.yyyy + */ + toStrDate(): string; + + /** + * Get a representation of the date suitable for a browser (yyyy-mm-dd) + * @returns {string} A string representing the date in the form yyyy-mm-dd + */ + toBrowserDate(): string; + + /** + * Get a representation of the time with seconds (hh:mm:ss) + * @returns {string} A string representing the time in the form hh:mm:ss + */ + toStrFullTime(): string; + + /** + * Get a representation of the time without seconds (hh:mm) + * @returns {string} A string representing the time in the form hh:mm + */ + toStrShortTime(): string; +} diff --git a/src/time/DateTimeRange.d.ts b/src/time/DateTimeRange.d.ts new file mode 100644 index 0000000..268272a --- /dev/null +++ b/src/time/DateTimeRange.d.ts @@ -0,0 +1,36 @@ +import DateTime from './DateTime'; + +export default class DateTimeRange { + /** + * Create a new DateTimeRange instance + * @constructor + * @param {DateTime} start - The start date value + * @param {DateTime} end - The end date value + */ + constructor(start: DateTime, end: DateTime); + + /** + * returns + * 10.10.2020 - 10.12.2023 + * 10.10 - 10.12.2020 + * 11 - 10.10.2020 + * 10.10.2020 + */ + toStrDate(): string; + + /** + * returns + * 10:30 - 14:40 + * 10:30 + */ + toStrShortTime(): string; + + /** + * returns + * 03.07.2023 18:00 - 04.07.2024 18:00 + * 04.08 18:00 - 03.07.2023 18:00 + * 04.07 18:00 - 05.07.2023 18:00 + * 18:00 - 19:35 05.07.2023 + */ + toStrDateShortTime(): string; +} diff --git a/src/time/Duration.d.ts b/src/time/Duration.d.ts new file mode 100644 index 0000000..2ecdfd0 --- /dev/null +++ b/src/time/Duration.d.ts @@ -0,0 +1,39 @@ +import DateTime from './DateTime'; + +export default class Duration { + /** + * Create a new Duration instance + * + * @param {number} duration - The duration in milliseconds + */ + constructor(duration: number); + + /** + * Calculate the duration between two dates + * + * @param {DateTime} from - The start date + * @param {DateTime} to - The end date + */ + static from(from: DateTime, to: DateTime): Duration; + + /** + * Calculate the duration from now to a date + * + * @param {DateTime} to - The end date + */ + static toNow(to: DateTime): Duration; + + get seconds(): number; + + get minutes(): number; + + get hours(): number; + + get days(): number; + + get weeks(): number; + + toStrByDays(lang?: string | null): string; + + toStr(lang?: string | null): string; +}