feat: more correct type defs + docs

carsonfarmer · vmx · commit 4eb0c60a835d · 2020-01-24T06:24:59.000-06:00
Using the default export only works in ES6+ modules, the export style is technically more correct. Also adds docs and removes extraneous namespace in favour of explicit types.
diff --git a/src/index.d.ts b/src/index.d.ts
@@ -1,29 +1,112 @@
-export type Version = 0 | 1
-export type Codec = string
-export type Multihash = Buffer
-export type BaseEncodedString = string
-export type MultibaseName = string
-
-export class CID {
-  constructor(version: Version, codec: Codec, multhash: Multihash, multibaseName?: MultibaseName)
-  constructor(cidStr: BaseEncodedString)
+/**
+ * Class representing a CID `<mbase><version><mcodec><mhash>`
+ * , as defined in [ipld/cid](https://github.com/multiformats/cid).
+ */
+declare class CID {
+  /**
+   * Create a new CID.
+   *
+   * The algorithm for argument input is roughly:
+   * ```
+   * if (cid)
+   *   -> create a copy
+   * else if (str)
+   *   if (1st char is on multibase table) -> CID String
+   *   else -> bs58 encoded multihash
+   * else if (Buffer)
+   *   if (1st byte is 0 or 1) -> CID
+   *   else -> multihash
+   * else if (Number)
+   *   -> construct CID by parts
+   * ```
+   *
+   * @example
+   * new CID(<version>, <codec>, <multihash>, <multibaseName>)
+   * new CID(<cidStr>)
+   * new CID(<cid.buffer>)
+   * new CID(<multihash>)
+   * new CID(<bs58 encoded multihash>)
+   * new CID(<cid>)
+   */
+  constructor(version: 0 | 1, codec: string, multhash: Buffer, multibaseName?: string)
+  constructor(cidStr: string)
   constructor(cidBuf: Buffer)
-  constructor(cidMultihash: Multihash)
+  constructor(cidMultihash: Buffer)
   constructor(cid: CID)
-  codec: Codec
-  multihash: Multihash
-  buffer: Buffer
-  prefix: Buffer
+  
+  /**
+   * The codec of the CID.
+   */
+  codec: string
+
+  /**
+   * The multihash of the CID.
+   */
+  multihash: Buffer
+
+  /**
+   * Multibase name as string.
+   */
+  multibaseName: string
+
+  /**
+   * The CID as a `Buffer`
+   */
+  readonly buffer: Buffer
+  
+  /**
+   * The prefix of the CID.
+   */
+  readonly prefix: Buffer
+
+  /**
+   * The version of the CID.
+   */
   version: number
+
+  /**
+   * Convert to a CID of version `0`.
+   */
   toV0(): CID
+
+  /**
+   * Convert to a CID of version `1`.
+   */
   toV1(): CID
-  toBaseEncodedString(base?: string): BaseEncodedString
-  toString(): BaseEncodedString
-  toJSON(): { codec: Codec, version: Version, hash: Multihash }
+  /**
+   * Encode the CID into a string.
+   *
+   * @param base Base encoding to use.
+   */
+  toBaseEncodedString(base?: string): string
+
+  /**
+   * Encode the CID into a string.
+   */
+  toString(): string
+
+  /**
+   * Serialize to a plain object.
+   */
+  toJSON(): { codec: string, version: 0 | 1, hash: Buffer }
+  
+  /**
+   * Compare equality with another CID.
+   *
+   * @param other The other CID.
+   */
   equals(other: any): boolean
-  static codecs: Record<Codec, Buffer>
+  
+  static codecs: Record<string, Buffer>
   static isCID(mixed: any): boolean
+
+  /**
+   * Test if the given input is a valid CID object.
+   * Throws if it is not.
+   *
+   * @param other The other CID.
+   */
   static validateCID(other: any): void
 }
 
-export default CID
+export = CID
