@atproto/common-web 0.1.0 → 0.2.0

package/dist/ipld.d.ts

@@ -7,3 +7,4 @@ export declare type IpldValue = JsonValue | CID | Uint8Array | Array<IpldValue>
 };
 export declare const jsonToIpld: (val: JsonValue) => IpldValue;
 export declare const ipldToJson: (val: IpldValue) => JsonValue;
+export declare const ipldEquals: (a: IpldValue, b: IpldValue) => boolean;

package/dist/strings.d.ts

@@ -1,2 +1,16 @@
 export declare const utf8Len: (str: string) => number;
 export declare const graphemeLen: (str: string) => number;
+export declare const utf8ToB64Url: (utf8: string) => string;
+export declare const b64UrlToUtf8: (b64: string) => string;
+export declare const parseLanguage: (langTag: string) => LanguageTag | null;
+export declare const validateLanguage: (langTag: string) => boolean;
+export declare type LanguageTag = {
+    grandfathered?: string;
+    language?: string;
+    extlang?: string;
+    script?: string;
+    region?: string;
+    variant?: string;
+    extension?: string;
+    privateUse?: string;
+};

package/dist/tid.d.ts

@@ -5,8 +5,8 @@ export declare class TID {
     static nextStr(): string;
     static fromTime(timestamp: number, clockid: number): TID;
     static fromStr(str: string): TID;
-    static newestFirst(a: TID, b: TID): number;
     static oldestFirst(a: TID, b: TID): number;
+    static newestFirst(a: TID, b: TID): number;
     static is(str: string): boolean;
     timestamp(): number;
     clockid(): number;

package/dist/types.d.ts

@@ -17,3 +17,4 @@ export declare const def: {
     unknown: Def<unknown>;
 };
 export declare type ArrayEl<A> = A extends readonly (infer T)[] ? T : never;
+export declare type NotEmptyArray<T> = [T, ...T[]];

package/dist/util.d.ts

@@ -1,12 +1,12 @@
-/// <reference types="node" />
 export declare const noUndefinedVals: <T>(obj: Record<string, T>) => Record<string, T>;
+export declare const jitter: (maxMs: number) => number;
 export declare const wait: (ms: number) => Promise<unknown>;
 export declare const bailableWait: (ms: number) => {
     bail: () => void;
     wait: () => Promise<void>;
 };
 export declare const flattenUint8Arrays: (arrs: Uint8Array[]) => Uint8Array;
-export declare const streamToArray: (stream: AsyncIterable<Uint8Array>) => Promise<Uint8Array>;
+export declare const streamToBuffer: (stream: AsyncIterable<Uint8Array>) => Promise<Uint8Array>;
 export declare const s32encode: (i: number) => string;
 export declare const s32decode: (s: string) => number;
 export declare const asyncFilter: <T>(arr: T[], fn: (t: T) => Promise<boolean>) => Promise<T[]>;
@@ -14,3 +14,5 @@ export declare const isErrnoException: (err: unknown) => err is NodeJS.ErrnoExce
 export declare const errHasMsg: (err: unknown, msg: string) => boolean;
 export declare const chunkArray: <T>(arr: T[], chunkSize: number) => T[][];
 export declare const range: (num: number) => number[];
+export declare const dedupeStrs: (strs: string[]) => string[];
+export declare const parseIntWithFallback: <T>(value: string | undefined, fallback: T) => number | T;

package/package.json

@@ -1,12 +1,17 @@
 {
   "name": "@atproto/common-web",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "main": "dist/index.js",
   "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/bluesky-social/atproto.git",
+    "directory": "packages/common-web"
+  },
   "scripts": {
     "test": "jest",
-    "prettier": "prettier --check src/",
-    "prettier:fix": "prettier --write src/",
+    "prettier": "prettier --check src/ tests/",
+    "prettier:fix": "prettier --write src/ tests/",
     "lint": "eslint . --ext .ts,.tsx",
     "lint:fix": "yarn lint --fix",
     "verify": "run-p prettier lint",
@@ -19,8 +24,9 @@
     "postpublish": "npm run update-main-to-src"
   },
   "dependencies": {
+    "graphemer": "^1.4.0",
     "multiformats": "^9.6.4",
     "uint8arrays": "3.0.0",
-    "zod": "^3.14.2"
+    "zod": "^3.21.4"
   }
 }

package/src/ipld.ts

@@ -75,3 +75,32 @@ export const ipldToJson = (val: IpldValue): JsonValue => {
   // pass through
   return val as JsonValue
 }
+
+export const ipldEquals = (a: IpldValue, b: IpldValue): boolean => {
+  // walk arrays
+  if (Array.isArray(a) && Array.isArray(b)) {
+    if (a.length !== b.length) return false
+    for (let i = 0; i < a.length; i++) {
+      if (!ipldEquals(a[i], b[i])) return false
+    }
+    return true
+  }
+  // objects
+  if (a && b && typeof a === 'object' && typeof b === 'object') {
+    // check bytes
+    if (a instanceof Uint8Array && b instanceof Uint8Array) {
+      return ui8.equals(a, b)
+    }
+    // check cids
+    if (CID.asCID(a) && CID.asCID(b)) {
+      return CID.asCID(a)?.equals(CID.asCID(b))
+    }
+    // walk plain objects
+    if (Object.keys(a).length !== Object.keys(b).length) return false
+    for (const key of Object.keys(a)) {
+      if (!ipldEquals(a[key], b[key])) return false
+    }
+    return true
+  }
+  return a === b
+}

package/src/strings.ts

@@ -1,3 +1,6 @@
+import Graphemer from 'graphemer'
+import * as ui8 from 'uint8arrays'
+
 // counts the number of bytes in a utf8 string
 export const utf8Len = (str: string): number => {
   return new TextEncoder().encode(str).byteLength
@@ -5,5 +8,49 @@ export const utf8Len = (str: string): number => {
 
 // counts the number of graphemes (user-displayed characters) in a string
 export const graphemeLen = (str: string): number => {
-  return [...new Intl.Segmenter().segment(str)].length
+  const splitter = new Graphemer()
+  return splitter.countGraphemes(str)
+}
+
+export const utf8ToB64Url = (utf8: string): string => {
+  return ui8.toString(ui8.fromString(utf8, 'utf8'), 'base64url')
+}
+
+export const b64UrlToUtf8 = (b64: string): string => {
+  return ui8.toString(ui8.fromString(b64, 'base64url'), 'utf8')
+}
+
+export const parseLanguage = (langTag: string): LanguageTag | null => {
+  const parsed = langTag.match(bcp47Regexp)
+  if (!parsed?.groups) return null
+  const parts = parsed.groups
+  return {
+    grandfathered: parts.grandfathered,
+    language: parts.language,
+    extlang: parts.extlang,
+    script: parts.script,
+    region: parts.region,
+    variant: parts.variant,
+    extension: parts.extension,
+    privateUse: parts.privateUseA || parts.privateUseB,
+  }
+}
+
+export const validateLanguage = (langTag: string): boolean => {
+  return bcp47Regexp.test(langTag)
 }
+
+export type LanguageTag = {
+  grandfathered?: string
+  language?: string
+  extlang?: string
+  script?: string
+  region?: string
+  variant?: string
+  extension?: string
+  privateUse?: string
+}
+
+// Validates well-formed BCP 47 syntax: https://www.rfc-editor.org/rfc/rfc5646.html#section-2.1
+const bcp47Regexp =
+  /^((?<grandfathered>(en-GB-oed|i-ami|i-bnn|i-default|i-enochian|i-hak|i-klingon|i-lux|i-mingo|i-navajo|i-pwn|i-tao|i-tay|i-tsu|sgn-BE-FR|sgn-BE-NL|sgn-CH-DE)|(art-lojban|cel-gaulish|no-bok|no-nyn|zh-guoyu|zh-hakka|zh-min|zh-min-nan|zh-xiang))|((?<language>([A-Za-z]{2,3}(-(?<extlang>[A-Za-z]{3}(-[A-Za-z]{3}){0,2}))?)|[A-Za-z]{4}|[A-Za-z]{5,8})(-(?<script>[A-Za-z]{4}))?(-(?<region>[A-Za-z]{2}|[0-9]{3}))?(-(?<variant>[A-Za-z0-9]{5,8}|[0-9][A-Za-z0-9]{3}))*(-(?<extension>[0-9A-WY-Za-wy-z](-[A-Za-z0-9]{2,8})+))*(-(?<privateUseA>x(-[A-Za-z0-9]{1,8})+))?)|(?<privateUseB>x(-[A-Za-z0-9]{1,8})+))$/

package/src/tid.ts

@@ -1,14 +1,21 @@
 import { s32encode, s32decode } from './util'
+
+const TID_LEN = 13
+
 let lastTimestamp = 0
 let timestampCount = 0
 let clockid: number | null = null
 
+function dedash(str: string): string {
+  return str.replaceAll('-', '')
+}
+
 export class TID {
   str: string
 
   constructor(str: string) {
-    const noDashes = str.replace(/-/g, '')
-    if (noDashes.length !== 13) {
+    const noDashes = dedash(str)
+    if (noDashes.length !== TID_LEN) {
       throw new Error(`Poorly formatted TID: ${noDashes.length} length`)
     }
     this.str = noDashes
@@ -46,31 +53,24 @@ export class TID {
     return new TID(str)
   }
 
-  static newestFirst(a: TID, b: TID): number {
-    return a.compareTo(b) * -1
-  }
-
   static oldestFirst(a: TID, b: TID): number {
     return a.compareTo(b)
   }
 
+  static newestFirst(a: TID, b: TID): number {
+    return b.compareTo(a)
+  }
+
   static is(str: string): boolean {
-    try {
-      TID.fromStr(str)
-      return true
-    } catch (err) {
-      return false
-    }
+    return dedash(str).length === TID_LEN
   }
 
   timestamp(): number {
-    const substr = this.str.slice(0, 11)
-    return s32decode(substr)
+    return s32decode(this.str.slice(0, 11))
   }
 
   clockid(): number {
-    const substr = this.str.slice(11, 13)
-    return s32decode(substr)
+    return s32decode(this.str.slice(11, 13))
   }
 
   formatted(): string {
@@ -93,7 +93,7 @@ export class TID {
   }
 
   equals(other: TID): boolean {
-    return this.compareTo(other) === 0
+    return this.str === other.str
   }
 
   newerThan(other: TID): boolean {

package/src/types.ts

@@ -42,3 +42,5 @@ export const def = {
 }
 
 export type ArrayEl<A> = A extends readonly (infer T)[] ? T : never
+
+export type NotEmptyArray<T> = [T, ...T[]]

package/src/util.ts

@@ -9,6 +9,10 @@ export const noUndefinedVals = <T>(
   return obj
 }
 
+export const jitter = (maxMs: number) => {
+  return Math.round((Math.random() - 0.5) * maxMs * 2)
+}
+
 export const wait = (ms: number) => {
   return new Promise((res) => setTimeout(res, ms))
 }
@@ -40,7 +44,7 @@ export const flattenUint8Arrays = (arrs: Uint8Array[]): Uint8Array => {
   return flattened
 }
 
-export const streamToArray = async (
+export const streamToBuffer = async (
   stream: AsyncIterable<Uint8Array>,
 ): Promise<Uint8Array> => {
   const arrays: Uint8Array[] = []
@@ -106,3 +110,15 @@ export const range = (num: number): number[] => {
   }
   return nums
 }
+
+export const dedupeStrs = (strs: string[]): string[] => {
+  return [...new Set(strs)]
+}
+
+export const parseIntWithFallback = <T>(
+  value: string | undefined,
+  fallback: T,
+): number | T => {
+  const parsed = parseInt(value || '', 10)
+  return isNaN(parsed) ? fallback : parsed
+}

package/tests/check.test.ts

@@ -0,0 +1,89 @@
+import { check } from '../src/index'
+import { ZodError } from 'zod'
+
+describe('check', () => {
+  describe('is', () => {
+    it('checks object against definition', () => {
+      const checkable: check.Checkable<boolean> = {
+        parse(obj) {
+          return Boolean(obj)
+        },
+        safeParse(obj) {
+          return {
+            success: true,
+            data: Boolean(obj),
+          }
+        },
+      }
+
+      expect(check.is(true, checkable)).toBe(true)
+    })
+
+    it('handles failed checks', () => {
+      const checkable: check.Checkable<boolean> = {
+        parse(obj) {
+          return Boolean(obj)
+        },
+        safeParse() {
+          return {
+            success: false,
+            error: new ZodError([]),
+          }
+        },
+      }
+
+      expect(check.is(true, checkable)).toBe(false)
+    })
+  })
+
+  describe('assure', () => {
+    it('returns value on success', () => {
+      const checkable: check.Checkable<boolean> = {
+        parse(obj) {
+          return Boolean(obj)
+        },
+        safeParse(obj) {
+          return {
+            success: true,
+            data: Boolean(obj),
+          }
+        },
+      }
+
+      expect(check.assure(checkable, true)).toEqual(true)
+    })
+
+    it('throws on failure', () => {
+      const err = new Error('foo')
+      const checkable: check.Checkable<boolean> = {
+        parse() {
+          throw err
+        },
+        safeParse() {
+          throw err
+        },
+      }
+
+      expect(() => check.assure(checkable, true)).toThrow(err)
+    })
+  })
+
+  describe('isObject', () => {
+    const falseTestValues: unknown[] = [null, undefined, 'foo', 123, true]
+
+    for (const obj of falseTestValues) {
+      it(`returns false for ${obj}`, () => {
+        expect(check.isObject(obj)).toBe(false)
+      })
+    }
+
+    it('returns true for objects', () => {
+      expect(check.isObject({})).toBe(true)
+    })
+
+    it('returns true for instances of classes', () => {
+      const obj = new (class {})()
+      expect(check.isObject(obj)).toBe(true)
+    })
+  })
+})

package/tests/strings.test.ts

@@ -1,4 +1,4 @@
-import { graphemeLen, utf8Len } from '../src'
+import { graphemeLen, parseLanguage, utf8Len, validateLanguage } from '../src'
 
 describe('string', () => {
   it('calculates utf8 string length', () => {
@@ -14,7 +14,7 @@ describe('string', () => {
     expect(utf8Len('👨‍👩‍👧‍👧')).toBe(25)
   })
 
-  it('caluclates grapheme length', () => {
+  it('calculates grapheme length', () => {
     expect(graphemeLen('a')).toBe(1)
     expect(graphemeLen('~')).toBe(1)
     expect(graphemeLen('ö')).toBe(1)
@@ -27,4 +27,88 @@ describe('string', () => {
     expect(graphemeLen('👨‍👩‍👧‍👧')).toBe(1)
     expect(graphemeLen('a~öñ©⽘☎𓋓😀👨‍👩‍👧‍👧')).toBe(10)
   })
+
+  describe('languages', () => {
+    it('validates BCP 47', () => {
+      // valid
+      expect(validateLanguage('de')).toEqual(true)
+      expect(validateLanguage('de-CH')).toEqual(true)
+      expect(validateLanguage('de-DE-1901')).toEqual(true)
+      expect(validateLanguage('es-419')).toEqual(true)
+      expect(validateLanguage('sl-IT-nedis')).toEqual(true)
+      expect(validateLanguage('mn-Cyrl-MN')).toEqual(true)
+      expect(validateLanguage('x-fr-CH')).toEqual(true)
+      expect(
+        validateLanguage('en-GB-boont-r-extended-sequence-x-private'),
+      ).toEqual(true)
+      expect(validateLanguage('sr-Cyrl')).toEqual(true)
+      expect(validateLanguage('hy-Latn-IT-arevela')).toEqual(true)
+      expect(validateLanguage('i-klingon')).toEqual(true)
+      // invalid
+      expect(validateLanguage('')).toEqual(false)
+      expect(validateLanguage('x')).toEqual(false)
+      expect(validateLanguage('de-CH-')).toEqual(false)
+      expect(validateLanguage('i-bad-grandfathered')).toEqual(false)
+    })
+
+    it('parses BCP 47', () => {
+      // valid
+      expect(parseLanguage('de')).toEqual({
+        language: 'de',
+      })
+      expect(parseLanguage('de-CH')).toEqual({
+        language: 'de',
+        region: 'CH',
+      })
+      expect(parseLanguage('de-DE-1901')).toEqual({
+        language: 'de',
+        region: 'DE',
+        variant: '1901',
+      })
+      expect(parseLanguage('es-419')).toEqual({
+        language: 'es',
+        region: '419',
+      })
+      expect(parseLanguage('sl-IT-nedis')).toEqual({
+        language: 'sl',
+        region: 'IT',
+        variant: 'nedis',
+      })
+      expect(parseLanguage('mn-Cyrl-MN')).toEqual({
+        language: 'mn',
+        script: 'Cyrl',
+        region: 'MN',
+      })
+      expect(parseLanguage('x-fr-CH')).toEqual({
+        privateUse: 'x-fr-CH',
+      })
+      expect(
+        parseLanguage('en-GB-boont-r-extended-sequence-x-private'),
+      ).toEqual({
+        language: 'en',
+        region: 'GB',
+        variant: 'boont',
+        extension: 'r-extended-sequence',
+        privateUse: 'x-private',
+      })
+      expect(parseLanguage('sr-Cyrl')).toEqual({
+        language: 'sr',
+        script: 'Cyrl',
+      })
+      expect(parseLanguage('hy-Latn-IT-arevela')).toEqual({
+        language: 'hy',
+        script: 'Latn',
+        region: 'IT',
+        variant: 'arevela',
+      })
+      expect(parseLanguage('i-klingon')).toEqual({
+        grandfathered: 'i-klingon',
+      })
+      // invalid
+      expect(parseLanguage('')).toEqual(null)
+      expect(parseLanguage('x')).toEqual(null)
+      expect(parseLanguage('de-CH-')).toEqual(null)
+      expect(parseLanguage('i-bad-grandfathered')).toEqual(null)
+    })
+  })
 })

package/tests/tid.test.ts

@@ -15,4 +15,122 @@ describe('TIDs', () => {
     expect(parsed.timestamp()).toEqual(tid.timestamp())
     expect(parsed.clockid()).toEqual(tid.clockid())
   })
+
+  it('throws if invalid tid passed', () => {
+    expect(() => new TID('')).toThrow('Poorly formatted TID: 0 length')
+  })
+
+  describe('nextStr', () => {
+    it('returns next tid as a string', () => {
+      const str = TID.nextStr()
+      expect(typeof str).toEqual('string')
+      expect(str.length).toEqual(13)
+    })
+  })
+
+  describe('newestFirst', () => {
+    it('sorts tids newest first', () => {
+      const oldest = TID.next()
+      const newest = TID.next()
+
+      const tids = [oldest, newest]
+
+      tids.sort(TID.newestFirst)
+
+      expect(tids).toEqual([newest, oldest])
+    })
+  })
+
+  describe('oldestFirst', () => {
+    it('sorts tids oldest first', () => {
+      const oldest = TID.next()
+      const newest = TID.next()
+
+      const tids = [newest, oldest]
+
+      tids.sort(TID.oldestFirst)
+
+      expect(tids).toEqual([oldest, newest])
+    })
+  })
+
+  describe('is', () => {
+    it('true for valid tids', () => {
+      const tid = TID.next()
+      const asStr = tid.toString()
+
+      expect(TID.is(asStr)).toBe(true)
+    })
+
+    it('false for invalid tids', () => {
+      expect(TID.is('')).toBe(false)
+    })
+  })
+
+  describe('equals', () => {
+    it('true when same tid', () => {
+      const tid = TID.next()
+      expect(tid.equals(tid)).toBe(true)
+    })
+
+    it('true when different instance, same tid', () => {
+      const tid0 = TID.next()
+      const tid1 = new TID(tid0.toString())
+
+      expect(tid0.equals(tid1)).toBe(true)
+    })
+
+    it('false when different tid', () => {
+      const tid0 = TID.next()
+      const tid1 = TID.next()
+
+      expect(tid0.equals(tid1)).toBe(false)
+    })
+  })
+
+  describe('newerThan', () => {
+    it('true for newer tid', () => {
+      const tid0 = TID.next()
+      const tid1 = TID.next()
+
+      expect(tid1.newerThan(tid0)).toBe(true)
+    })
+
+    it('false for older tid', () => {
+      const tid0 = TID.next()
+      const tid1 = TID.next()
+
+      expect(tid0.newerThan(tid1)).toBe(false)
+    })
+
+    it('false for identical tids', () => {
+      const tid0 = TID.next()
+      const tid1 = new TID(tid0.toString())
+
+      expect(tid0.newerThan(tid1)).toBe(false)
+    })
+  })
+
+  describe('olderThan', () => {
+    it('true for older tid', () => {
+      const tid0 = TID.next()
+      const tid1 = TID.next()
+
+      expect(tid0.olderThan(tid1)).toBe(true)
+    })
+
+    it('false for newer tid', () => {
+      const tid0 = TID.next()
+      const tid1 = TID.next()
+
+      expect(tid1.olderThan(tid0)).toBe(false)
+    })
+
+    it('false for identical tids', () => {
+      const tid0 = TID.next()
+      const tid1 = new TID(tid0.toString())
+
+      expect(tid0.olderThan(tid1)).toBe(false)
+    })
+  })
 })