@synnaxlabs/freighter 0.2.0 → 0.4.1

package/src/lib/caseconv.ts

@@ -1,13 +0,0 @@
-import {
-  camelKeys as _camelKeys,
-  snakeKeys as _snakeKeys,
-} from 'js-convert-case';
-
-const options = {
-  recursive: true,
-  recursiveInArray: true,
-  keepTypesOnRecursion: [Number, String, Uint8Array],
-};
-
-export const snakeKeys = (entity: unknown) => _snakeKeys(entity, options);
-export const camelKeys = (entity: unknown) => _camelKeys(entity, options);

package/src/lib/encoder.spec.ts

@@ -1,23 +0,0 @@
-import test from 'ava';
-import { z } from 'zod';
-
-import { ENCODERS } from './encoder';
-
-const SampleSchema = z.object({
-  channelKey: z.string(),
-  timeStamp: z.number(),
-  value: z.unknown(),
-});
-
-ENCODERS.forEach((encoder) => {
-  test(`[encoder] - encoder ${encoder.contentType}`, (t) => {
-    const sample = {
-      channelKey: 'test',
-      timeStamp: 123,
-      value: new Uint8Array([1, 2, 3]),
-    };
-    const encoded = encoder.encode(sample);
-    const decoded = encoder.decode(encoded, SampleSchema);
-    t.deepEqual(decoded, decoded);
-  });
-});

package/src/lib/encoder.ts

@@ -1,105 +0,0 @@
-import { addExtension, pack, unpack } from 'msgpackr';
-import { ZodSchema } from 'zod';
-
-import { camelKeys, snakeKeys } from './caseconv';
-
-/**
- * CustomTypeEncoder is an interface for a class that needs to transform its
- * value before encoding.
- */
-interface CustomTypeEncoder {
-  /** The Class the custom encoder is set for */
-  // eslint-disable-next-line @typescript-eslint/ban-types
-  Class: Function;
-
-  /**
-   * The function that transforms the value before encoding;
-   *
-   * @param instance - The instance of the class to transform.
-   * @returns The transformed value.
-   */
-  write<P>(instance: P): unknown;
-}
-
-/**
- * EncoderDecoder is an entity that encodes and decodes messages to and from a
- * binary format.
- */
-export interface EncoderDecoder {
-  /** The HTTP content type of the encoder */
-  contentType: string;
-
-  /**
-   * Encodes the given payload into a binary representation.
-   *
-   * @param payload - The payload to encode.
-   * @returns An ArrayBuffer containing the encoded payload.
-   */
-  encode(payload: unknown): ArrayBuffer;
-
-  /**
-   * Decodes the given binary representation into a type checked payload.
-   *
-   * @param data - The data to decode.
-   * @param schema - The schema to decode the data with.
-   */
-  decode<P>(data: Uint8Array | ArrayBuffer, schema: ZodSchema<P>): P;
-}
-
-interface StaticEncoderDecoder {
-  registerCustomType(encoder: CustomTypeEncoder): void;
-}
-
-/** MsgpackEncoderDecoder is a msgpack implementation of EncoderDecoder. */
-export class MsgpackEncoderDecoder implements EncoderDecoder {
-  contentType = 'application/msgpack';
-
-  encode(payload: unknown): ArrayBuffer {
-    return pack(snakeKeys(payload));
-  }
-
-  decode<P>(data: Uint8Array, schema: ZodSchema<P>): P {
-    return schema.parse(camelKeys(unpack(new Uint8Array(data))));
-  }
-
-  static registerCustomType(encoder: CustomTypeEncoder): void {
-    addExtension({ type: 0, ...encoder });
-  }
-}
-
-/** JSONEncoderDecoder is a JSON implementation of EncoderDecoder. */
-export class JSONEncoderDecoder implements EncoderDecoder {
-  contentType = 'application/json';
-
-  encode(payload: unknown): ArrayBuffer {
-    const json = JSON.stringify(snakeKeys(payload), (_, v) => {
-      if (ArrayBuffer.isView(v)) return Array.from(v as Uint8Array);
-      return v;
-    });
-    return new TextEncoder().encode(json);
-  }
-
-  decode<P>(data: Uint8Array, schema: ZodSchema<P>): P {
-    return schema.parse(camelKeys(JSON.parse(new TextDecoder().decode(data))));
-  }
-
-  static registerCustomType(): void {
-    return;
-  }
-}
-
-export const ENCODERS: EncoderDecoder[] = [
-  new MsgpackEncoderDecoder(),
-  new JSONEncoderDecoder(),
-];
-
-export const ENCODER_CLASSES: StaticEncoderDecoder[] = [
-  MsgpackEncoderDecoder,
-  JSONEncoderDecoder,
-];
-
-export const registerCustomTypeEncoder = (encoder: CustomTypeEncoder): void => {
-  ENCODER_CLASSES.forEach((encoderClass) => {
-    encoderClass.registerCustomType(encoder);
-  });
-};

package/src/lib/errors.spec.ts

@@ -1,98 +0,0 @@
-import test from 'ava';
-
-import {
-  assertErrorType,
-  BaseTypedError,
-  decodeError,
-  encodeError,
-  EOF,
-  FREIGHTER,
-  isTypedError,
-  NONE,
-  registerError,
-  StreamClosed,
-  TypedError,
-  UNKNOWN,
-  UnknownError,
-  Unreachable,
-} from './errors';
-
-class MyCustomError extends BaseTypedError {
-  constructor(message: string) {
-    super(message, 'MyCustomError');
-  }
-}
-
-const myCustomErrorEncoder = (error: MyCustomError): string => {
-  return error.message;
-};
-
-const myCustomErrorDecoder = (encoded: string): TypedError => {
-  return new MyCustomError(encoded);
-};
-
-test('isTypedError', (t) => {
-  const error = new MyCustomError('test');
-  const fError = isTypedError(error);
-  t.is(fError, true);
-  t.is(error.type, 'MyCustomError');
-});
-
-test('encoding and decoding a custom error through registry', (t) => {
-  registerError({
-    type: 'MyCustomError',
-    encode: myCustomErrorEncoder,
-    decode: myCustomErrorDecoder,
-  });
-  const error = new MyCustomError('test');
-  const encoded = encodeError(error);
-  t.is(encoded.type, 'MyCustomError');
-  t.is(encoded.data, 'test');
-  const decoded = assertErrorType<MyCustomError>(
-    'MyCustomError',
-    decodeError(encoded)
-  );
-  t.is(decoded.message, 'test');
-});
-
-test('encoding and decoding a null error', (t) => {
-  const encoded = encodeError(null);
-  t.is(encoded.type, NONE);
-  t.is(encoded.data, '');
-  const decoded = decodeError(encoded);
-  t.is(decoded, undefined);
-});
-
-test('encoding and decoding an unrecognized error', (t) => {
-  const error = new Error('test');
-  const encoded = encodeError(error);
-  t.is(encoded.type, UNKNOWN);
-  t.is(encoded.data, '{}');
-  const decoded = decodeError(encoded);
-  t.deepEqual(decoded, new UnknownError('{}'));
-});
-
-test('registering duplicate error should throw', (t) => {
-  registerError({
-    type: 'MyDuplicateError',
-    encode: myCustomErrorEncoder,
-    decode: myCustomErrorDecoder,
-  });
-  t.throws(() => {
-    registerError({
-      type: 'MyDuplicateError',
-      encode: myCustomErrorEncoder,
-      decode: myCustomErrorDecoder,
-    });
-  });
-});
-
-test('encoding and decoding freighter errors', (t) => {
-  [new EOF(), new StreamClosed(), new Unreachable()].forEach((error) => {
-    const encoded = encodeError(error);
-    t.is(encoded.type, FREIGHTER);
-    t.is(encoded.data, error.message);
-    const decoded = decodeError(encoded);
-    t.deepEqual(decoded, error);
-  });
-});

package/src/lib/errors.ts

@@ -1,214 +0,0 @@
-import { z } from 'zod';
-
-export interface TypedError extends Error {
-  discriminator: 'FreighterError';
-  /**
-   * @description Returns a unique type identifier for the error. Freighter uses this to
-   * determine the correct decoder to use on the other end of the freighter.
-   */
-  type: string;
-}
-
-export class BaseTypedError extends Error implements TypedError {
-  discriminator: 'FreighterError' = 'FreighterError';
-  type: string;
-
-  constructor(message: string, type: string) {
-    super(message);
-    this.type = type;
-  }
-}
-
-type ErrorDecoder = (encoded: string) => Error | undefined;
-type ErrorEncoder = (error: TypedError) => string;
-
-export const isTypedError = (error: unknown): error is TypedError => {
-  if (!error || typeof error !== 'object') {
-    return false;
-  }
-  const typedError = error as TypedError;
-  if (typedError.discriminator !== 'FreighterError') {
-    return false;
-  }
-  if (!('type' in typedError)) {
-    throw new Error(
-      `Freighter error is missing its type property: ${typedError}`
-    );
-  }
-  return true;
-};
-
-export const assertErrorType = <T>(type: string, error?: Error): T => {
-  if (!error) {
-    throw new Error(`Expected error of type ${type} but got nothing instead`);
-  }
-  if (!isTypedError(error)) {
-    throw new Error(`Expected a typed error, got: ${error}`);
-  }
-  if (error.type !== type) {
-    throw new Error(
-      `Expected error of type ${type}, got ${error.type}: ${error}`
-    );
-  }
-  return error as unknown as T;
-};
-
-export const UNKNOWN = 'unknown';
-export const NONE = 'nil';
-export const FREIGHTER = 'freighter';
-
-export const ErrorPayloadSchema = z.object({
-  type: z.string(),
-  data: z.string(),
-});
-
-export type ErrorPayload = z.infer<typeof ErrorPayloadSchema>;
-
-type errorProvider = {
-  encode: ErrorEncoder;
-  decode: ErrorDecoder;
-};
-
-class Registry {
-  private readonly entries: { [type: string]: errorProvider };
-
-  constructor() {
-    this.entries = {};
-  }
-
-  register(_type: string, provider: errorProvider) {
-    if (this.entries[_type]) {
-      throw new Error(`Error type ${_type} is already registered`);
-    }
-    this.entries[_type] = provider;
-  }
-
-  encode(error: unknown): ErrorPayload {
-    if (!error) {
-      return { type: NONE, data: '' };
-    }
-    if (isTypedError(error) && this.entries[error.type]) {
-      return { type: error.type, data: this.entries[error.type].encode(error) };
-    }
-    return { type: UNKNOWN, data: JSON.stringify(error) };
-  }
-
-  decode(payload: ErrorPayload): Error | undefined {
-    if (payload.type === NONE) {
-      return undefined;
-    }
-
-    if (payload.type === UNKNOWN) {
-      return new UnknownError(payload.data);
-    }
-
-    const provider = this.entries[payload.type];
-    if (!provider) {
-      return new UnknownError(payload.data);
-    }
-    return provider.decode(payload.data);
-  }
-}
-
-const REGISTRY = new Registry();
-
-/**
- * Registers a custom error type with the error registry, which allows it to be
- * encoded/decoded and sent over the network.
- *
- * @param type - A unique string identifier for the error type.
- * @param encode - A function that encodes the error into a string.
- * @param decode - A function that decodes the error from a string.
- */
-export const registerError = ({
-  type,
-  encode,
-  decode,
-}: {
-  type: string;
-  encode: ErrorEncoder;
-  decode: ErrorDecoder;
-}) => {
-  REGISTRY.register(type, { encode, decode });
-};
-
-/**
- * Encodes an error into a payload that can be sent between a freighter server
- * and client.
- * @param error - The error to encode.
- * @returns The encoded error.
- */
-export const encodeError = (error: unknown): ErrorPayload => {
-  return REGISTRY.encode(error);
-};
-
-/**
- * Decodes an error payload into an exception. If a custom decoder can be found
- * for the error type, it will be used. Otherwise, a generic Error containing
- * the error data is returned.
- *
- * @param payload - The encoded error payload.
- * @returns The decoded error.
- */
-export const decodeError = (payload: ErrorPayload): Error | undefined => {
-  return REGISTRY.decode(payload);
-};
-
-export class UnknownError extends BaseTypedError implements TypedError {
-  constructor(message: string) {
-    super(message, UNKNOWN);
-  }
-}
-
-/** Thrown/returned when a stream closed normally. */
-export class EOF extends BaseTypedError implements TypedError {
-  constructor() {
-    super('EOF', FREIGHTER);
-  }
-}
-
-/** Thrown/returned when a stream is closed abnormally. */
-export class StreamClosed extends BaseTypedError implements TypedError {
-  constructor() {
-    super('StreamClosed', FREIGHTER);
-  }
-}
-
-/** Thrown when a target is unreachable. */
-export class Unreachable extends BaseTypedError implements TypedError {
-  constructor() {
-    super('Unreachable', FREIGHTER);
-  }
-}
-
-const freighterErrorEncoder: ErrorEncoder = (error: TypedError) => {
-  if (error instanceof EOF) {
-    return 'EOF';
-  }
-  if (error instanceof StreamClosed) {
-    return 'StreamClosed';
-  }
-  if (error instanceof Unreachable) {
-    return 'Unreachable';
-  }
-  throw new Error(`Unknown error type: ${error}`);
-};
-
-const freighterErrorDecoder: ErrorDecoder = (encoded: string) => {
-  switch (encoded) {
-    case 'EOF':
-      return new EOF();
-    case 'StreamClosed':
-      return new StreamClosed();
-    case 'Unreachable':
-      return new Unreachable();
-    default:
-      throw new Error(`Unknown error type: ${encoded}`);
-  }
-};
-
-registerError({
-  type: FREIGHTER,
-  encode: freighterErrorEncoder,
-  decode: freighterErrorDecoder,
-});

package/src/lib/http.spec.ts

@@ -1,85 +0,0 @@
-import test from 'ava';
-import { z } from 'zod';
-
-import { JSONEncoderDecoder } from './encoder';
-import { HTTPClientFactory } from './http';
-import URL from './url';
-
-const ENDPOINT = new URL({
-  host: '127.0.0.1',
-  port: 8080,
-  pathPrefix: 'unary',
-});
-
-const factory = new HTTPClientFactory(ENDPOINT, new JSONEncoderDecoder());
-
-const MessageSchema = z.object({
-  id: z.number().optional(),
-  message: z.string().optional(),
-});
-
-type Message = z.infer<typeof MessageSchema>;
-
-const getClient = factory.getClient();
-const postClient = factory.postClient();
-
-test('[http] - post echo', async (t) => {
-  const [response, error] = await postClient.send<Message, Message>(
-    '/echo',
-    {
-      id: 1,
-      message: 'hello',
-    },
-    MessageSchema
-  );
-  t.is(error, undefined);
-  t.deepEqual(response, { id: 2, message: 'hello' });
-});
-
-test('[http] - get echo', async (t) => {
-  const [response, error] = await getClient.send<Message, Message>(
-    '/echo',
-    {
-      id: 1,
-      message: 'hello',
-    },
-    MessageSchema
-  );
-  t.is(error, undefined);
-  t.deepEqual(response, { id: 2, message: 'hello' });
-});
-
-test('[http] - get not found', async (t) => {
-  const [response, error] = await getClient.send<Message, Message>(
-    '/not-found',
-    {},
-    MessageSchema
-  );
-  t.is(error?.message, 'Cannot GET /unary/not-found');
-  t.is(response, undefined);
-});
-
-test('[http] - post not found', async (t) => {
-  const [response, error] = await postClient.send<Message, Message>(
-    '/not-found',
-    {},
-    MessageSchema
-  );
-  t.is(error?.message, 'Cannot POST /unary/not-found');
-  t.is(response, undefined);
-});
-
-test('[http] - middleware', async (t) => {
-  const client = factory.getClient();
-  client.use(async (md, next) => {
-    md.params['Test'] = 'test';
-    return await next(md);
-  });
-  const [response, error] = await client.send<Message, Message>(
-    '/middlewareCheck',
-    {},
-    MessageSchema
-  );
-  t.is(error, undefined);
-  t.is(response?.message, '');
-});

package/src/lib/http.ts

@@ -1,149 +0,0 @@
-import axios, { AxiosRequestConfig } from 'axios';
-import { ZodSchema } from 'zod';
-
-import { EncoderDecoder } from './encoder';
-import { decodeError, ErrorPayloadSchema } from './errors';
-import { MetaData, MiddlewareCollector } from './middleware';
-import { UnaryClient } from './unary';
-import URL from './url';
-
-/**
- * HTTPClientFactory provides a POST and GET implementation of the Unary
- * protocol.
- *
- * @param url - The base URL of the API.
- * @param encoder - The encoder/decoder to use for the request/response.
- */
-export class HTTPClientFactory extends MiddlewareCollector {
-  endpoint: URL;
-  encoder: EncoderDecoder;
-
-  constructor(endpoint: URL, encoder: EncoderDecoder) {
-    super();
-    this.endpoint = endpoint;
-    this.encoder = encoder;
-  }
-
-  getClient(): GETClient {
-    const gc = new GETClient(this.endpoint, this.encoder);
-    gc.use(...this.middleware);
-    return gc;
-  }
-
-  postClient(): POSTClient {
-    const pc = new POSTClient(this.endpoint, this.encoder);
-    pc.use(...this.middleware);
-    return pc;
-  }
-}
-
-export const CONTENT_TYPE_HEADER_KEY = 'Content-Type';
-
-class Core extends MiddlewareCollector {
-  endpoint: URL;
-  encoder: EncoderDecoder;
-
-  constructor(endpoint: URL, encoder: EncoderDecoder) {
-    super();
-    this.endpoint = endpoint.replace({ protocol: 'http' });
-    this.encoder = encoder;
-  }
-
-  get headers() {
-    return {
-      [CONTENT_TYPE_HEADER_KEY]: this.encoder.contentType,
-    };
-  }
-
-  requestConfig(): AxiosRequestConfig {
-    return {
-      headers: this.headers,
-      responseType: 'arraybuffer',
-      withCredentials: false,
-      validateStatus: () => true,
-    };
-  }
-
-  async execute<RS>(
-    request: AxiosRequestConfig,
-    resSchema: ZodSchema<RS>
-  ): Promise<[RS | undefined, Error | undefined]> {
-    let rs: RS | undefined = undefined;
-
-    if (!request.url)
-      throw new Error('[freighter.http] - expected valid request url');
-
-    const err = await this.executeMiddleware(
-      { target: request.url, protocol: 'http', params: {} },
-      async (md: MetaData): Promise<Error | undefined> => {
-        request.headers = { ...request.headers, ...this.headers, ...md.params };
-        const httpRes = await axios.request(request);
-        if (httpRes.status < 200 || httpRes.status >= 300) {
-          try {
-            const err = this.encoder.decode(httpRes.data, ErrorPayloadSchema);
-            return decodeError(err);
-          } catch {
-            return new Error(httpRes.data);
-          }
-        }
-        rs = this.encoder.decode(httpRes.data, resSchema);
-        return undefined;
-      }
-    );
-
-    return [rs, err];
-  }
-}
-
-/**
- * Implementation of the UnaryClient protocol backed by HTTP GET requests. It
- * should not be instantiated directly, but through the HTTPClientFactory.
- */
-export class GETClient extends Core implements UnaryClient {
-  async send<RQ, RS>(
-    target: string,
-    req: RQ,
-    resSchema: ZodSchema<RS>
-  ): Promise<[RS | undefined, Error | undefined]> {
-    const request = this.requestConfig();
-    request.method = 'GET';
-    request.url =
-      this.endpoint.child(target).stringify() +
-      buildQueryString({ request: req as Record<string, unknown> });
-    return await this.execute(request, resSchema);
-  }
-}
-
-/**
- * Implementation of the UnaryClient protocol backed by HTTP POST requests. It
- * should not be instantiated directly, but through the HTTPClientFactory.
- */
-export class POSTClient extends Core implements UnaryClient {
-  async send<RQ, RS>(
-    target: string,
-    req: RQ,
-    resSchema: ZodSchema<RS>
-  ): Promise<[RS | undefined, Error | undefined]> {
-    const url = this.endpoint.child(target).stringify();
-    const request = this.requestConfig();
-    request.method = 'POST';
-    request.url = url;
-    request.data = this.encoder.encode(req);
-    return await this.execute(request, resSchema);
-  }
-}
-
-export const buildQueryString = ({
-  request,
-  prefix = '',
-}: {
-  request: Record<string, unknown>;
-  prefix?: string;
-}) => {
-  return (
-    '?' +
-    Object.keys(request)
-      .map((key) => `${prefix}${key}=${request[key]}`)
-      .join('&')
-  );
-};

package/src/lib/runtime.ts

@@ -1,23 +0,0 @@
-export enum Runtime {
-  Browser = 'browser',
-  Node = 'node',
-}
-
-const detectRuntime = (): Runtime => {
-  if (
-    typeof process !== 'undefined' &&
-    process.versions != null &&
-    process.versions.node != null
-  ) {
-    return Runtime.Node;
-  }
-
-  if (typeof window !== 'undefined' && typeof window.document !== 'undefined') {
-    return Runtime.Browser;
-  }
-
-  console.warn('Freighter unable to safely detect runtime, assuming browser');
-  return Runtime.Browser;
-};
-
-export const RUNTIME = detectRuntime();