@rsdk/common 5.7.0-next.6 → 6.0.0-next.1

package/src/parsers/enum/enum.parser.ts

@@ -0,0 +1,24 @@
+import { Convert } from '../../convert';
+import type { EnumLike, EnumValue } from '../../enums';
+import { Enum } from '../../enums';
+import { text } from '../../strings';
+import type { PropertyParser } from '../parser.interface';
+
+export class EnumParser<E extends EnumValue> implements PropertyParser<E> {
+  constructor(private readonly enumeration: EnumLike) {}
+
+  type(): string {
+    return `string|number(enum_value)`;
+  }
+
+  description(): string {
+    return text`
+      Extracts strings or numbers and ensures it is one of:
+      ${Enum.values(this.enumeration).join(', ')}
+    `;
+  }
+
+  parse(value: unknown): E {
+    return Convert.enum<E>(value, this.enumeration);
+  }
+}

package/src/parsers/enum/enum.spec.ts

@@ -0,0 +1,5 @@
+describe('EnumParser', () => {
+  /* eslint-disable @typescript-eslint/no-empty-function */
+  it('See tests for Convert.enum() in @rsdk/common', () =>
+    expect(true).toBe(true));
+});

package/src/parsers/enum/index.ts

@@ -0,0 +1 @@
+export * from './enum.parser';

package/src/parsers/index.ts

@@ -0,0 +1,11 @@
+export * from './boolean';
+export * from './enum';
+export * from './int';
+export * from './number';
+export * from './size';
+export * from './string';
+export * from './timespan';
+export * from './url';
+export * from './array';
+export * from './json';
+export * from './parser.interface';

package/src/parsers/int/index.ts

@@ -0,0 +1 @@
+export * from './int.parser';

package/src/parsers/int/int.parser.ts

@@ -0,0 +1,20 @@
+import { Convert } from '../../convert';
+import { text } from '../../strings';
+import type { PropertyParser } from '../parser.interface';
+
+export class IntParser implements PropertyParser<number> {
+  type(): string {
+    return 'number(int)';
+  }
+
+  description(): string {
+    return text`
+      Extracts valid integer (uses parseInt under the hood).
+      Floating point numbers, NaN, Infinity will be rejected.
+    `;
+  }
+
+  parse(value: unknown): number {
+    return Convert.int(value);
+  }
+}

package/src/parsers/int/int.spec.ts

@@ -0,0 +1,5 @@
+describe('IntParser', () => {
+  /* eslint-disable @typescript-eslint/no-empty-function */
+  it('See tests for Convert.int() in @rsdk/common', () =>
+    expect(true).toBe(true));
+});

package/src/parsers/json/index.ts

@@ -0,0 +1 @@
+export * from './json.parser';

package/src/parsers/json/json.parser.ts

@@ -0,0 +1,15 @@
+import type { PropertyParser } from '../parser.interface';
+
+export class JsonParser implements PropertyParser<Record<string, any>> {
+  description(): string {
+    return 'parse string as json';
+  }
+
+  parse(value: string): Record<string, any> {
+    return JSON.parse(value);
+  }
+
+  type(): string {
+    return 'json';
+  }
+}

package/src/parsers/number/index.ts

@@ -0,0 +1 @@
+export * from './number.parser';

package/src/parsers/number/number.parser.ts

@@ -0,0 +1,23 @@
+import { Convert } from '../../convert';
+import { text } from '../../strings';
+import type { PropertyParser } from '../parser.interface';
+
+export class NumberParser implements PropertyParser<number> {
+  type(): string {
+    return 'number';
+  }
+
+  description(): string {
+    return text`
+      Extracts numeric value (uses parseFloat under the hood).
+      NaN and Infinity will be rejected.
+
+      NOTE: Use correct decimal delimiter according to locale. See
+      https://developer.mozilla.org/ru/docs/Web/JavaScript/Reference/Global_Objects/Intl
+    `;
+  }
+
+  parse(value: unknown): number {
+    return Convert.number(value);
+  }
+}

package/src/parsers/number/number.spec.ts

@@ -0,0 +1,5 @@
+describe('NumberParser', () => {
+  /* eslint-disable @typescript-eslint/no-empty-function */
+  it('See tests for Convert.number() in @rsdk/common', () =>
+    expect(true).toBe(true));
+});

package/src/parsers/parser.interface.ts

@@ -0,0 +1,22 @@
+/**
+ * Implement this interface to create more parsers.
+ * For example: email, BigInt, guid etc.
+ *
+ * NOTE: In other modules it is more common to define metadata
+ * via decorators. But this case is a bit different.
+ *
+ * 1. Parser implementations can have constructors with parameters
+ * which will affect it's behaviour. It's will be nice to have it
+ * in metadata, and decorators won't provide this.
+ *
+ * 2. Metadata will be extracted via type() and description() methods
+ * mostly during decorator factories (such as @Property()) code is
+ * executed. Thus output **can** be used in autodoc
+ */
+export interface PropertyParser<T = any> {
+  type(): string;
+
+  description(): string;
+
+  parse(value: unknown): T;
+}

package/src/parsers/size/index.ts

@@ -0,0 +1 @@
+export * from './size.parser';

package/src/parsers/size/size.parser.ts

@@ -0,0 +1,23 @@
+import { Size, SIZE_STRING_PATTERN } from '../../size';
+import { text } from '../../strings';
+import { Assert } from '../../types';
+import type { PropertyParser } from '../parser.interface';
+
+export class SizeParser implements PropertyParser<Size> {
+  type(): string {
+    return 'Timespan';
+  }
+
+  description(): string {
+    return text`
+      Parses string in size format into Timespan instance.
+      Format is: ${SIZE_STRING_PATTERN}. For example: 8b, 10kb, 2gb.
+    `;
+  }
+
+  parse(value: unknown): Size {
+    Assert.isString(value);
+
+    return Size.parse(value);
+  }
+}

package/src/parsers/size/size.spec.ts

@@ -0,0 +1,4 @@
+describe('SizeParser', () => {
+  /* eslint-disable @typescript-eslint/no-empty-function */
+  it('See tests in @rsdk/common', () => expect(true).toBe(true));
+});

package/src/parsers/string/index.ts

@@ -0,0 +1 @@
+export * from './string.parser';

package/src/parsers/string/string.parser.ts

@@ -0,0 +1,24 @@
+import { Assert } from '../../types';
+import type { PropertyParser } from '../parser.interface';
+
+export class StringParser implements PropertyParser<string> {
+  constructor(private readonly pattern?: RegExp) {}
+
+  type(): string {
+    return 'string';
+  }
+
+  description(): string {
+    return 'Extract arbitrary string.';
+  }
+
+  parse(value: unknown): string {
+    Assert.isString(value);
+
+    if (this.pattern) {
+      Assert.isTrue(this.pattern.test(value));
+    }
+
+    return value;
+  }
+}

package/src/parsers/string/string.spec.ts

@@ -0,0 +1,10 @@
+import { StringParser } from './string.parser';
+
+describe('StringMatcher', () => {
+  it('match', () => {
+    const parser = new StringParser(/^[a-z]+$/);
+
+    expect(parser.parse('abcd')).toBe('abcd');
+    expect(() => parser.parse('1234')).toThrow();
+  });
+});

package/src/parsers/timespan/index.ts

@@ -0,0 +1 @@
+export * from './timespan.parser';

package/src/parsers/timespan/timespan.parser.ts

@@ -0,0 +1,23 @@
+import { text } from '../../strings';
+import { Timespan, TIMESPAN_STRING_PATTERN } from '../../time';
+import { Assert } from '../../types';
+import type { PropertyParser } from '../parser.interface';
+
+export class TimespanParser implements PropertyParser<Timespan> {
+  type(): string {
+    return 'Timespan';
+  }
+
+  description(): string {
+    return text`
+      Parses string in timespan format into Timespan instance.
+      Format is: ${TIMESPAN_STRING_PATTERN}. For example: 1s, 2h, 4d.
+    `;
+  }
+
+  parse(value: unknown): Timespan {
+    Assert.isString(value);
+
+    return Timespan.parse(value);
+  }
+}

package/src/parsers/timespan/timespan.spec.ts

@@ -0,0 +1,5 @@
+describe('TimespanParser', () => {
+  /* eslint-disable @typescript-eslint/no-empty-function */
+  it('See tests for Timespan class in @rsdk/common', () =>
+    expect(true).toBe(true));
+});

package/src/parsers/url/errors.ts

@@ -0,0 +1,19 @@
+export class InvalidUrl extends Error {
+  constructor(str: string, cause: unknown) {
+    super(`Invalid url string: <${str}>`);
+    this.name = 'InvalidUrl';
+    this.cause = cause;
+  }
+}
+
+export class InvalidProtocol extends Error {
+  constructor(expectedProtocols: string[], protocol: string, url: URL) {
+    super(`Invalid protocol: <${protocol}>, expected: ${expectedProtocols}`);
+    this.name = 'InvalidProtocol';
+    this.cause = {
+      protocol,
+      url,
+      expected: expectedProtocols,
+    };
+  }
+}

package/src/parsers/url/index.ts

@@ -0,0 +1 @@
+export * from './url.parser';

package/src/parsers/url/url.parser.ts

@@ -0,0 +1,43 @@
+import { Assert } from '../../types';
+import type { PropertyParser } from '../parser.interface';
+
+import { InvalidProtocol, InvalidUrl } from './errors';
+
+export class UrlParser implements PropertyParser<URL> {
+  private readonly protocols: string[];
+
+  constructor(...protocols: string[]) {
+    this.protocols = protocols;
+  }
+
+  type(): string {
+    return 'URL';
+  }
+
+  description(): string {
+    return 'Parses string into instance of URL';
+  }
+
+  parse(value: unknown): URL {
+    Assert.isString(value);
+
+    try {
+      const url = new URL(value);
+
+      this.assertProtocol(url);
+      return url;
+    } catch (error) {
+      throw new InvalidUrl(value, error);
+    }
+  }
+
+  private assertProtocol(url: URL): void {
+    if (this.protocols.length === 0) {
+      return;
+    }
+
+    if (!this.protocols.includes(url.protocol)) {
+      throw new InvalidProtocol(this.protocols, url.protocol, url);
+    }
+  }
+}

package/src/types/assert.class.ts

@@ -15,6 +15,22 @@ export class Assert {
     throw new Error(`<${x}> is not a number.`);
   }
 
+  static isBoolean(x: unknown): asserts x is boolean {
+    if (typeof x === 'boolean') {
+      return;
+    }
+
+    throw new Error(`<${x}> is not a boolean.`);
+  }
+
+  static isTrue(x: unknown): asserts x is true {
+    if (x === true) {
+      return;
+    }
+
+    throw new Error(`<${x}> is not true.`);
+  }
+
   static isError(x: unknown): asserts x is Error {
     if (x instanceof Error) {
       return;