@outfoxx/sunday 1.0.9 → 1.1.0-alpha.11

package/src/media-type-codecs/www-form-url-encoder.ts

@@ -0,0 +1,193 @@
+// Copyright 2020 Outfox, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+import { Instant } from '@js-joda/core';
+import { JsonStringifier } from '@outfoxx/jackson-js';
+import { URLQueryParamsEncoder } from './media-type-encoder';
+
+export class WWWFormUrlEncoder implements URLQueryParamsEncoder {
+  static get default(): WWWFormUrlEncoder {
+    return new WWWFormUrlEncoder(
+      WWWFormUrlEncoder.ArrayEncoding.UNBRACKETED,
+      WWWFormUrlEncoder.BoolEncoding.LITERAL,
+      WWWFormUrlEncoder.DateEncoding.DECIMAL_SECONDS_SINCE_EPOCH
+    );
+  }
+
+  constructor(
+    private arrayEncoding: WWWFormUrlEncoder.ArrayEncoding,
+    private boolEncoding: WWWFormUrlEncoder.BoolEncoding,
+    private dateEncoding: WWWFormUrlEncoder.DateEncoding,
+    private json = new JsonStringifier(),
+    private encoder = new TextEncoder()
+  ) {}
+
+  encode<T = unknown>(value: T): ArrayBuffer | SharedArrayBuffer {
+    const parameters = this.json.transform(value);
+
+    return this.encoder.encode(this.encodeQueryString(parameters));
+  }
+
+  encodeQueryString(parameters: Record<string, unknown>): string {
+    const components: string[] = [];
+
+    for (const key of Object.keys(parameters).sort()) {
+      components.push(...this.encodeQueryComponent(key, parameters[key]));
+    }
+    return components.join('&');
+  }
+
+  encodeQueryComponent(key: string, value: unknown): string[] {
+    const components: string[] = [];
+
+    if (value === undefined) {
+      return components;
+    }
+
+    if (value == null) {
+      //
+      components.push(encodeURIComponent(key));
+    } else if (value instanceof Array) {
+      // encode key according to `arrayEncoding`
+      for (const item of value) {
+        components.push(
+          ...this.encodeQueryComponent(
+            encodeArrayKey(key, this.arrayEncoding),
+            item
+          )
+        );
+      }
+    } else if (value instanceof Instant) {
+      //
+      components.push(
+        encodeURIComponent(key) +
+          '=' +
+          encodeURIComponent(encodeDate(value, this.dateEncoding))
+      );
+    } else if (typeof value === 'boolean') {
+      //
+      components.push(
+        encodeURIComponent(key) +
+          '=' +
+          encodeURIComponent(encodeBoolean(value, this.boolEncoding))
+      );
+    } else if (typeof value === 'object') {
+      //
+      const rec = (value ?? {}) as Record<string, unknown>;
+
+      for (const nestedKey of Object.keys(rec).sort()) {
+        components.push(
+          ...this.encodeQueryComponent(`${key}[${nestedKey}]`, rec[nestedKey])
+        );
+      }
+    } else {
+      //
+      components.push(
+        encodeURIComponent(key) + '=' + encodeURIComponent(`${value}`)
+      );
+    }
+
+    return components;
+  }
+}
+
+function encodeArrayKey(
+  key: string,
+  encoding: WWWFormUrlEncoder.ArrayEncoding
+): string {
+  return encoding === WWWFormUrlEncoder.ArrayEncoding.BRACKETED
+    ? `${key}[]`
+    : key;
+}
+
+function encodeBoolean(
+  value: boolean,
+  encoding: WWWFormUrlEncoder.BoolEncoding
+): string {
+  switch (encoding) {
+    case WWWFormUrlEncoder.BoolEncoding.NUMERIC:
+      return value ? '1' : '0';
+    case WWWFormUrlEncoder.BoolEncoding.LITERAL:
+      return value ? 'true' : 'false';
+    default:
+      throw new Error('unknown boolean encoding');
+  }
+}
+
+function encodeDate(
+  value: Date | Instant,
+  encoding: WWWFormUrlEncoder.DateEncoding
+): string {
+  value = value instanceof Date ? Instant.ofEpochMilli(value.getTime()) : value;
+  switch (encoding) {
+    case WWWFormUrlEncoder.DateEncoding.DECIMAL_SECONDS_SINCE_EPOCH:
+      return (value.epochSecond() + value.nano() / 1_000_000_000.0).toFixed(7);
+    case WWWFormUrlEncoder.DateEncoding.MILLISECONDS_SINCE_EPOCH:
+      return `${value.toEpochMilli()}`;
+    case WWWFormUrlEncoder.DateEncoding.ISO8601:
+      return value.toString();
+    default:
+      throw new Error('unknown date encoding');
+  }
+}
+
+export namespace WWWFormUrlEncoder {
+  /**
+   * Configures how `Array` parameters are encoded.
+   */
+  export enum ArrayEncoding {
+    /**
+     * An empty set of square brackets is appended to the key for every value. This is the default behavior.
+     */
+    BRACKETED,
+    /**
+     * No brackets are appended. The key is encoded as is.
+     */
+    UNBRACKETED,
+  }
+
+  /**
+   * Configures how `Bool` parameters are encoded.
+   */
+  export enum BoolEncoding {
+    /**
+     * Encode `true` as `1` and `false` as `0`. This is the default behavior.
+     */
+    NUMERIC,
+    /**
+     * Encode `true` and `false` as string literals.
+     */
+    LITERAL,
+  }
+
+  /**
+   * Configures how `Date` parameters are encoded.
+   */
+  export enum DateEncoding {
+    /**
+     * Encode the `Date` as a UNIX timestamp (decimal seconds since epoch).
+     */
+    DECIMAL_SECONDS_SINCE_EPOCH,
+
+    /**
+     * Encode the `Date` as UNIX millisecond timestamp (integer milliseconds since epoch).
+     */
+    MILLISECONDS_SINCE_EPOCH,
+
+    /**
+     * Encode the `Date` as an ISO-8601-formatted string (in RFC 3339 format). This is the default behavior.
+     */
+    ISO8601,
+  }
+}

package/src/media-type.ts

@@ -1,25 +1,343 @@
-export enum MediaType {
-  TEXT = 'text/plain',
-  HTML = 'text/html',
-  JSON = 'application/json',
-  YAML = 'application/yaml',
-  CBOR = 'application/cbor',
-  OCTET_STREAM = 'application/octet-stream',
-  EVENT_STREAM = 'text/event-stream',
-  X509_CA_CERT = 'application/x-x509-ca-cert',
-  WWW_URL_FORM_ENCODED = 'application/x-www-form-urlencoded',
-  PROBLEM_JSON = 'application/problem+json',
+// Copyright 2020 Outfox, Inc.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+export class MediaType {
+  type: MediaType.Type;
+  tree: MediaType.Tree;
+  subtype: string;
+  suffix?: MediaType.Suffix;
+  parameters: Record<string, string>;
+
+  constructor(params: {
+    type: MediaType.Type;
+    tree?: MediaType.Tree;
+    subtype: string;
+    suffix?: MediaType.Suffix;
+    parameters?: Record<string, string>;
+  }) {
+    this.type = params.type;
+    this.tree = params.tree ?? MediaType.Tree.Standard;
+    this.subtype = params.subtype.toLowerCase();
+    this.suffix = params.suffix;
+    this.parameters = Object.entries(params.parameters ?? {}).reduce(
+      (obj, [name, value]) => {
+        obj[name.toLowerCase()] = value.toLowerCase();
+        return obj;
+      },
+      {} as Record<string, string>
+    );
+  }
+
+  parameter(name: MediaType.ParameterName | string): string | undefined {
+    return this.parameters[name];
+  }
+
+  with(params: {
+    type?: MediaType.Type;
+    tree?: MediaType.Tree;
+    subtype?: string;
+    suffix?: MediaType.Suffix;
+    parameters?: Record<string, string>;
+  }): MediaType {
+    return new MediaType({
+      type: params.type ?? this.type,
+      tree: params.tree ?? this.tree,
+      subtype: params.subtype ?? this.subtype,
+      suffix: params.suffix ?? this.suffix,
+      parameters: params.parameters ?? this.parameters,
+    });
+  }
+
+  withParameter(
+    parameter: MediaType.ParameterName | string,
+    value: string
+  ): MediaType {
+    const parameters = Object.assign({}, this.parameters, {
+      [parameter]: value,
+    });
+    return this.with({ parameters });
+  }
+
+  get value(): string {
+    const type = this.type;
+    const tree = this.tree;
+    const suffix = this.suffix ? `+${this.suffix.toLowerCase()}` : '';
+    const parameters = Object.keys(this.parameters)
+      .sort()
+      .map((key) => `;${key}=${this.parameters[key]}`)
+      .join('');
+    return `${type}/${tree}${this.subtype}${suffix}${parameters}`;
+  }
+
+  compatible(other: MediaType): boolean {
+    if (
+      this.type != MediaType.Type.Any &&
+      other.type != MediaType.Type.Any &&
+      this.type != other.type
+    ) {
+      return false;
+    }
+    if (
+      this.tree != MediaType.Tree.Any &&
+      other.tree != MediaType.Tree.Any &&
+      this.tree != other.tree
+    ) {
+      return false;
+    }
+    if (
+      this.subtype != '*' &&
+      other.subtype != '*' &&
+      this.subtype != other.subtype
+    ) {
+      return false;
+    }
+    if (this.suffix != other.suffix) {
+      return false;
+    }
+    const thisKeys = Object.keys(this.parameters);
+    const otherKeys = Object.keys(other.parameters);
+    return thisKeys
+      .filter((key) => otherKeys.includes(key))
+      .every((key) => this.parameters[key] == other.parameters[key]);
+  }
+
+  equals(other: MediaType): boolean {
+    if (this === other) return true;
+
+    if (this.type != other.type) return false;
+    if (this.tree != other.tree) return false;
+    if (this.suffix != other.suffix) return false;
+    if (this.subtype != other.subtype) return false;
+    for (const parameterName of Object.keys(this.parameters)) {
+      if (this.parameters[parameterName] != other.parameters[parameterName]) {
+        return false;
+      }
+    }
+    return true;
+  }
+
+  toString(): string {
+    return this.value;
+  }
 }
 
-export function mediaType(value: string | null | undefined): string | undefined;
-export function mediaType(
-  value: string | null | undefined,
-  def: string
-): string;
-
-export function mediaType(
-  value: string | null | undefined,
-  def?: string
-): string | undefined {
-  return value?.split(';')[0].trim() ?? def;
+export namespace MediaType {
+  export enum Type {
+    Application = 'application',
+    Audio = 'audio',
+    Example = 'example',
+    Font = 'font',
+    Image = 'image',
+    Message = 'message',
+    Model = 'model',
+    Multipart = 'multipart',
+    Text = 'text',
+    Video = 'video',
+    Any = '*',
+  }
+
+  export namespace Type {
+    export function from(value: string): Type | undefined {
+      return Object.values(Type).includes(value as Type)
+        ? (value as Type)
+        : undefined;
+    }
+  }
+
+  export enum Tree {
+    Standard = '',
+    Vendor = 'vnd.',
+    Personal = 'prs.',
+    Unregistered = 'x.',
+    Obsolete = 'x-',
+    Any = '*',
+  }
+
+  export namespace Tree {
+    export function from(value: string): Tree | undefined {
+      return Object.values(Tree).includes(value as Tree)
+        ? (value as Tree)
+        : undefined;
+    }
+  }
+
+  export enum Suffix {
+    XML = 'xml',
+    JSON = 'json',
+    BER = 'ber',
+    DER = 'der',
+    FastInfoSet = 'fastinfoset',
+    WBXML = 'wbxml',
+    Zip = 'zip',
+    CBOR = 'cbor',
+  }
+
+  export namespace Suffix {
+    export function from(value: string): Suffix | undefined {
+      return Object.values(Suffix).includes(value as Suffix)
+        ? (value as Suffix)
+        : undefined;
+    }
+  }
+
+  export enum ParameterName {
+    CharSet = 'charset',
+  }
+
+  export function from(value?: string | null): MediaType | undefined;
+  export function from(
+    value: string | null | undefined,
+    def: MediaType
+  ): MediaType;
+  export function from(
+    value?: string | null,
+    def: MediaType | undefined = undefined
+  ): MediaType | undefined {
+    if (!value) {
+      return def;
+    }
+
+    fullRegex.lastIndex = 0;
+    const match = fullRegex.exec(value);
+    if (match?.[0] != value) {
+      return def;
+    }
+
+    const type = MediaType.Type.from(match[1]?.toLowerCase());
+    if (!type) {
+      return def;
+    }
+
+    const tree =
+      MediaType.Tree.from(match[2]?.toLowerCase()) ?? MediaType.Tree.Standard;
+
+    const subtype = match[3]?.toLowerCase();
+    if (!subtype) {
+      return def;
+    }
+
+    const suffix = MediaType.Suffix.from(match[4]?.toLowerCase());
+
+    const parameters: Record<string, string> = {};
+
+    let parametersMatch = paramRegex.exec(match[5] ?? '');
+    while (parametersMatch?.[0]) {
+      const name = parametersMatch[1];
+      if (!name) continue;
+
+      const value = parametersMatch[2];
+      if (!value) continue;
+
+      parameters[name.toLowerCase()] = value.toLowerCase();
+
+      parametersMatch = paramRegex.exec(match[5]);
+    }
+
+    return new MediaType({
+      type,
+      tree,
+      subtype,
+      suffix,
+      parameters,
+    });
+  }
+
+  const fullRegex =
+    /^((?:[a-z]+|\*))\/(x(?:-|\\.)|(?:(?:vnd|prs|x)\.)|\*)?([a-z0-9\-.]+|\*)(?:\+([a-z]+))?( *(?:; *(?:(?:[\w.-]+) *= *(?:[\w.-]+)) *)*)$/gi;
+  const paramRegex = / *; *([\w.-]+) *= *([\w.-]+)/gi;
+
+  export const Plain = new MediaType({
+    type: MediaType.Type.Text,
+    subtype: 'plain',
+  });
+  export const HTML = new MediaType({
+    type: MediaType.Type.Text,
+    subtype: 'html',
+  });
+  export const JSON = new MediaType({
+    type: MediaType.Type.Application,
+    subtype: 'json',
+  });
+  export const YAML = new MediaType({
+    type: MediaType.Type.Application,
+    subtype: 'yaml',
+  });
+  export const CBOR = new MediaType({
+    type: MediaType.Type.Application,
+    subtype: 'cbor',
+  });
+  export const EventStream = new MediaType({
+    type: MediaType.Type.Text,
+    subtype: 'event-stream',
+  });
+  export const OctetStream = new MediaType({
+    type: MediaType.Type.Application,
+    subtype: 'octet-stream',
+  });
+  export const WWWFormUrlEncoded = new MediaType({
+    type: MediaType.Type.Application,
+    tree: MediaType.Tree.Obsolete,
+    subtype: 'www-form-urlencoded',
+  });
+  export const X509CACert = new MediaType({
+    type: MediaType.Type.Application,
+    tree: MediaType.Tree.Obsolete,
+    subtype: 'x509-ca-cert',
+  });
+  export const X509UserCert = new MediaType({
+    type: MediaType.Type.Application,
+    tree: MediaType.Tree.Obsolete,
+    subtype: 'x509-user-cert',
+  });
+
+  export const Any = new MediaType({
+    type: MediaType.Type.Any,
+    subtype: '*',
+  });
+  export const AnyText = new MediaType({
+    type: MediaType.Type.Text,
+    subtype: '*',
+  });
+  export const AnyImage = new MediaType({
+    type: MediaType.Type.Image,
+    subtype: '*',
+  });
+  export const AnyAudio = new MediaType({
+    type: MediaType.Type.Audio,
+    subtype: '*',
+  });
+  export const AnyVideo = new MediaType({
+    type: MediaType.Type.Video,
+    subtype: '*',
+  });
+
+  export const JSONStructured = new MediaType({
+    type: MediaType.Type.Any,
+    tree: MediaType.Tree.Any,
+    subtype: '*',
+    suffix: Suffix.JSON,
+  });
+  export const XMLStructured = new MediaType({
+    type: MediaType.Type.Any,
+    tree: MediaType.Tree.Any,
+    subtype: '*',
+    suffix: Suffix.XML,
+  });
+
+  export const ProblemJSON = new MediaType({
+    type: MediaType.Type.Application,
+    subtype: 'problem',
+    suffix: Suffix.JSON,
+  });
 }