BREAKING!: feat @cordis/util

README.md

@@ -35,7 +35,6 @@ Cordis is cut up in the form of multiple packages/libraries:
 - [`@cordis/redis-store`](https://github.com/cordis-lib/cordis/tree/main/libs/redis-store) - A Redis implementation of `@cordis/store`
 - [`@cordis/rest`](https://github.com/cordis-lib/cordis/tree/main/libs/rest) - Tooling for making HTTP requests to Discord, with rate limiting handling
 - [`@cordis/routers`](https://github.com/cordis-lib/cordis/tree/main/libs/routers) - Make API requests with ease using simple dynamic JavaScript property accessing
-- [`@cordis/snowflake`](https://github.com/cordis-lib/cordis/tree/main/libs/snowflake) - A simple snowflake structure for destructuring Discord IDs into relevant information
 - [`@cordis/store`](https://github.com/cordis-lib/cordis/tree/main/libs/store) - A simple map-like interface for holding key-value pairs - ships with an in-memory implementation
 
 # Contributing

libs/common/src/functions/functions.test.ts

@@ -1,5 +1,4 @@
-import { getMissingProps, halt, isPromise, keyMirror, makeDiscordCdnUrl } from './';
-import { CordisUtilTypeError, CordisUtilRangeError } from '../error';
+import { getMissingProps, halt, isPromise, keyMirror } from './';
 
 test('get missing props', () => {
   const obj = { one: 1, two: 2 };
@@ -37,39 +36,3 @@ describe('is promise', () => {
 test('key mirror', () => {
   expect(keyMirror(['b'])).toStrictEqual({ b: 'b' });
 });
-
-describe('make discord cdn url', () => {
-  describe('invalid options handling', () => {
-    test('invalid format', () => {
-      const root = 'e16be7c509d54bb53b1ee21fe8d8cdac';
-      // @ts-expect-error Intentionally invalid format
-      expect(() => makeDiscordCdnUrl(root, { format: 'asdf' })).toThrow(CordisUtilTypeError);
-    });
-
-    test('invalid size', () => {
-      const root = 'e16be7c509d54bb53b1ee21fe8d8cdac';
-      // @ts-expect-error Intentionally invalid size
-      expect(() => makeDiscordCdnUrl(root, { size: 1 })).toThrow(CordisUtilRangeError);
-    });
-  });
-
-  test('defaults using an image', () => {
-    const root = 'e16be7c509d54bb53b1ee21fe8d8cdac';
-    expect(makeDiscordCdnUrl(root)).toBe(`${root}.webp`);
-  });
-
-  test('defaults using a gif', () => {
-    const root = 'a_bbab2f9b0bcecf438b4810c67798bfca';
-    expect(makeDiscordCdnUrl(root)).toBe(`${root}.gif`);
-  });
-
-  test('non-dynamic with a gif', () => {
-    const root = 'a_bbab2f9b0bcecf438b4810c67798bfca';
-    expect(makeDiscordCdnUrl(root, { dynamic: false })).toBe(`${root}.webp`);
-  });
-
-  test('valid custom size', () => {
-    const root = 'e16be7c509d54bb53b1ee21fe8d8cdac';
-    expect(makeDiscordCdnUrl(root, { size: 16 })).toBe(`${root}.webp?size=16`);
-  });
-});

libs/common/src/functions/index.ts

@@ -2,4 +2,3 @@ export * from './getMissingProps';
 export * from './halt';
 export * from './isPromise';
 export * from './keyMirror';
-export * from './makeDiscordCdnUrl';

libs/rest/src/RestManager.ts

@@ -205,7 +205,7 @@ export class RestManager extends EventEmitter {
    * @param options Other options for the request
    */
   /* istanbul ignore next */
-  public post<T, D = RequestBodyData>(path: string, options: { data: D; reason?: string; files?: File[] }): Promise<T> {
-    return this.make<T, D, never>({ path, method: 'post', ...options });
+  public post<T, D = RequestBodyData, Q = StringRecord>(path: string, options: { data: D; reason?: string; files?: File[]; query?: Q }): Promise<T> {
+    return this.make<T, D, Q>({ path, method: 'post', ...options });
   }
 }

libs/routers/src/IRouter.ts

@@ -5,5 +5,5 @@ export type IRouter = {
   delete<T, D = RequestBodyData>(options?: { data?: D; reason?: string }): Promise<T>;
   patch<T, D = RequestBodyData>(options: { data: D; reason?: string }): Promise<T>;
   put<T, D = RequestBodyData>(options?: { data?: D; reason?: string }): Promise<T>;
-  post<T, D = RequestBodyData>(options: { data: D; reason?: string; files?: File[] }): Promise<T>;
+  post<T, D = RequestBodyData, Q = StringRecord>(options: { data: D; reason?: string; files?: File[]; query?: Q }): Promise<T>;
 } & { [key: string]: IRouter };

libs/snowflake/README.md → libs/util/README.md

@@ -1,15 +1,15 @@
-# `@cordis/snowflake`  
+# `@cordis/util`  
 
 [![GitHub](https://img.shields.io/badge/License-Apache%202.0-yellow.svg)](https://github.com/cordis-lib/cordis/blob/main/LICENSE)
-[![npm](https://img.shields.io/npm/v/@cordis/snowflake?color=crimson&logo=npm)](https://www.npmjs.com/package/@cordis/snowflake)
+[![npm](https://img.shields.io/npm/v/@cordis/util?color=crimson&logo=npm)](https://www.npmjs.com/package/@cordis/util)
 [![TypeScript](https://github.com/cordis-lib/cordis/actions/workflows/quality.yml/badge.svg)](https://github.com/cordis-lib/cordis/actions/workflows/quality.yml)
 
-Simple package for destructuring (Twitter) Discord snowflakes.
+Helper methods and structures for Cordis
 
 ## Installation
-- `npm install @cordis/snowflake` 
-- `pnpm install @cordis/snowflake` 
-- `yarn add @cordis/snowflake`
+- `npm install @cordis/util` 
+- `pnpm install @cordis/util` 
+- `yarn add @cordis/util`
 
 ## Documentation
 You can find documentation for the whole project over at https://cordis.js.org

libs/snowflake/package.json → libs/util/package.json

@@ -1,9 +1,9 @@
 {
-  "name": "@cordis/snowflake",
-  "description": "Utility structure for dealing with Discord snowflakes",
+  "name": "@cordis/util",
+  "version": "0.1.7",
+  "description": "Helper methods and structures for Cordis",
   "main": "./dist/index.js",
   "types": "./types/index.d.ts",
-  "version": "0.1.7",
   "scripts": {
     "lint": "eslint src --ext .ts",
     "build": "tsc"
@@ -24,7 +24,7 @@
     "Holo-Buckshot (https://github.com/Holo-Buckshot)",
     "Nico (https://github.com/zaida04)"
   ],
-  "author": "didinele",
+  "author": "Zaid \"Nico\"",
   "bugs": {
     "url": "https://github.com/cordis-lib/cordis/issues"
   },
@@ -34,6 +34,8 @@
     "typescript": "^4.2.2"
   },
   "dependencies": {
+    "@cordis/rest": "workspace:^0.1.6",
+    "@cordis/error": "workspace:^0.1.6",
     "tslib": "^2.1.0"
   }
 }

libs/snowflake/src/index.test.ts → libs/util/src/Snowflake.test.ts

@@ -1,4 +1,4 @@
-import { Snowflake, getCreationData } from './';
+import { Snowflake, getCreationData } from './Snowflake';
 
 const ID = '223703707118731264';
 const CREATED_AT = 1473405519991;

libs/util/src/embed.test.ts

@@ -0,0 +1,80 @@
+import { buildEmbed } from './embed';
+
+test('Dataless value checks', () => {
+  const embed1 = buildEmbed({});
+  expect(embed1.author).toBe(undefined);
+  expect(embed1.color).toBe(undefined);
+  expect(embed1.description).toBe(undefined);
+  expect(embed1.footer).toBe(undefined);
+  expect(embed1.fields).toStrictEqual([]);
+  expect(embed1.image).toBe(undefined);
+  expect(embed1.provider).toBe(undefined);
+  expect(embed1.thumbnail).toBe(undefined);
+  expect(embed1.timestamp).toBe(undefined);
+  expect(embed1.title).toBe(undefined);
+  expect(embed1.author).toBe(undefined);
+  expect(embed1.url).toBe(undefined);
+  expect(embed1.video).toBe(undefined);
+});
+
+test('Data value checks', () => {
+  const date = new Date('2021-03-08T14:40:27.875Z');
+  const color = 16753920;
+
+  let embed2 = buildEmbed({
+    title: 'testing title!',
+    description: 'testing description',
+    url: 'https://google.com',
+    color,
+    fields: [],
+    thumbnail: {
+      url: 'https://google.com'
+    },
+    image: {
+      url: 'https://lh3.googleusercontent.com/proxy/K6J0xWzyfl729xgnZLj55qd5L0us_QN7m5MbcQgV09xP-HVw8Z_iJDwpXexcy87ZkHHrins6rMFwPahgPI-VI_il_gedMlBD7IIll_0e4AZNBg'
+    },
+    author: {
+      name: 'Test Author'
+    },
+    footer: {
+      text: 'Test Footer'
+    }
+  }).setTimestamp(date.getTime());
+
+  expect(embed2.timestamp).toBe(date.toString());
+  expect(embed2.color).toBe(color);
+  expect(embed2.fields).toStrictEqual([]);
+
+  embed2 = embed2
+    .setAuthor('testing_author_3')
+    .setColor(16753920)
+    .setDescription('I am testing changing descriptions')
+    .setFooter('bing bong', 'https://www.youtube.com/watch?v=dQw4w9WgXcQ')
+    .setImage('https://static.wikia.nocookie.net/youtubepoop/images/2/2a/Rick_Ashley.png/revision/latest/scale-to-width-down/340?cb=20130102175058')
+    .setThumbnail('https://static.wikia.nocookie.net/youtubepoop/images/2/2a/Rick_Ashley.png/revision/latest/scale-to-width-down/340?cb=20130102175058')
+    .setTitle('Never gonna give you up')
+    .setURL('http://yahoo.com')
+    .addFields({ name: 'never gonna', value: 'let you down', inline: true }, { name: 'never gonna run around and', value: 'desert you' });
+
+  expect(embed2.toJSON()).toMatchObject({
+    title: 'Never gonna give you up',
+    description: 'I am testing changing descriptions',
+    url: 'http://yahoo.com',
+    color: 16753920,
+    fields: [{ name: 'never gonna', value: 'let you down', inline: true }, { name: 'never gonna run around and', value: 'desert you' }],
+    thumbnail: {
+      url: 'https://static.wikia.nocookie.net/youtubepoop/images/2/2a/Rick_Ashley.png/revision/latest/scale-to-width-down/340?cb=20130102175058'
+    },
+    image: {
+      url: 'https://static.wikia.nocookie.net/youtubepoop/images/2/2a/Rick_Ashley.png/revision/latest/scale-to-width-down/340?cb=20130102175058'
+    },
+    author: {
+      name: 'testing_author_3'
+    },
+    type: 'rich',
+    footer: {
+      text: 'bing bong',
+      icon_url: 'https://www.youtube.com/watch?v=dQw4w9WgXcQ'
+    }
+  });
+});

libs/util/src/embed.ts

@@ -0,0 +1,43 @@
+import { APIEmbed, APIEmbedField, EmbedType } from 'discord-api-types/v8';
+
+export const buildEmbed = (embedData: Partial<APIEmbed> = {}) => {
+  embedData.fields ??= [];
+  embedData.type = EmbedType.Rich;
+
+  return {
+    ...Object.freeze(embedData),
+    toJSON: () => embedData,
+
+    setAuthor(name: string, url?: string, icon_url?: string, proxy_icon_url?: string) {
+      return buildEmbed({ ...this, author: { name, url, icon_url, proxy_icon_url } });
+    },
+    setColor(color: number) {
+      return buildEmbed({ ...this, color });
+    },
+    setDescription(description: string) {
+      return buildEmbed({ ...this, description });
+    },
+    setFooter(text: string, icon_url?: string, proxy_icon_url?: string) {
+      return buildEmbed({ ...this, footer: { text, icon_url, proxy_icon_url } });
+    },
+    setImage(url: string, proxy_url?: string, height?: number, width?: number) {
+      return buildEmbed({ ...this, image: { url, proxy_url, height, width } });
+    },
+    setThumbnail(url: string, proxy_url?: string, height?: number, width?: number) {
+      return buildEmbed({ ...this, thumbnail: { url, proxy_url, height, width } });
+    },
+    setTitle(title: string) {
+      return buildEmbed({ ...this, title });
+    },
+    setURL(url: string) {
+      return buildEmbed({ ...this, url });
+    },
+    setTimestamp(timestamp: Date | number = new Date()) {
+      if (typeof timestamp === 'number') timestamp = new Date(timestamp);
+      return buildEmbed({ ...this, timestamp: timestamp.toString() });
+    },
+    addFields(...data: APIEmbedField[]) {
+      return buildEmbed({ ...this, fields: embedData.fields?.concat(data) ?? data });
+    }
+  };
+};

libs/util/src/index.ts

@@ -0,0 +1,4 @@
+export * from './embed';
+export * from './makeDiscordCdnUrl';
+export * from './restUtils';
+export * from './Snowflake';

libs/util/src/makeDiscordCdnUrl.test.ts

@@ -0,0 +1,36 @@
+import { makeDiscordCdnUrl } from './';
+import { CordisUtilTypeError, CordisUtilRangeError } from './error';
+
+describe('invalid options handling', () => {
+  test('invalid format', () => {
+    const root = 'e16be7c509d54bb53b1ee21fe8d8cdac';
+    // @ts-expect-error Intentionally invalid format
+    expect(() => makeDiscordCdnUrl(root, { format: 'asdf' })).toThrow(CordisUtilTypeError);
+  });
+
+  test('invalid size', () => {
+    const root = 'e16be7c509d54bb53b1ee21fe8d8cdac';
+    // @ts-expect-error Intentionally invalid size
+    expect(() => makeDiscordCdnUrl(root, { size: 1 })).toThrow(CordisUtilRangeError);
+  });
+});
+
+test('defaults using an image', () => {
+  const root = 'e16be7c509d54bb53b1ee21fe8d8cdac';
+  expect(makeDiscordCdnUrl(root)).toBe(`${root}.webp`);
+});
+
+test('defaults using a gif', () => {
+  const root = 'a_bbab2f9b0bcecf438b4810c67798bfca';
+  expect(makeDiscordCdnUrl(root)).toBe(`${root}.gif`);
+});
+
+test('non-dynamic with a gif', () => {
+  const root = 'a_bbab2f9b0bcecf438b4810c67798bfca';
+  expect(makeDiscordCdnUrl(root, { dynamic: false })).toBe(`${root}.webp`);
+});
+
+test('valid custom size', () => {
+  const root = 'e16be7c509d54bb53b1ee21fe8d8cdac';
+  expect(makeDiscordCdnUrl(root, { size: 16 })).toBe(`${root}.webp?size=16`);
+});

libs/common/src/functions/makeDiscordCdnUrl.ts → libs/util/src/makeDiscordCdnUrl.ts

@@ -1,4 +1,4 @@
-import { CordisUtilTypeError, CordisUtilRangeError } from '../error';
+import { CordisUtilTypeError, CordisUtilRangeError } from './error';
 
 /**
  * Valid image formats