From a5070aea6e6e5e6fc2ef72f901fdaa970c172939 Mon Sep 17 00:00:00 2001 From: Carson Farmer Date: Mon, 27 Jan 2020 03:07:52 -0800 Subject: [PATCH] feat: adds typescript types + type tests (#110) * feat: adds typescript types + type tests Signed-off-by: Carson Farmer * feat: updates to latest cids release Signed-off-by: Carson Farmer --- package.json | 9 ++- src/index.d.ts | 188 +++++++++++++++++++++++++++++++++++++++++++ test/peer-id.spec.js | 4 + tsconfig.json | 37 +++++++++ 4 files changed, 236 insertions(+), 2 deletions(-) create mode 100644 src/index.d.ts create mode 100644 tsconfig.json diff --git a/package.json b/package.json index 32110de..74914ee 100644 --- a/package.json +++ b/package.json @@ -4,6 +4,7 @@ "description": "IPFS Peer Id implementation in Node.js", "leadMaintainer": "Vasco Santos ", "main": "src/index.js", + "types": "src/index.d.ts", "bin": "src/bin.js", "scripts": { "lint": "aegir lint", @@ -11,6 +12,7 @@ "test": "aegir test", "test:node": "aegir test -t node", "test:browser": "aegir test -t browser -t webworker", + "test:types": "npx tsc", "release": "aegir release", "release-minor": "aegir release --type minor", "release-major": "aegir release --type major", @@ -34,15 +36,18 @@ }, "homepage": "https://github.com/libp2p/js-peer-id", "devDependencies": { + "@types/chai": "^4.2.7", + "@types/dirty-chai": "^2.0.2", + "@types/mocha": "^5.2.7", "aegir": "^20.0.0", "bundlesize": "~0.18.0", "chai": "^4.2.0", "dirty-chai": "^2.0.1" }, "dependencies": { - "cids": "~0.7.1", + "cids": "^0.7.3", "class-is": "^1.1.0", - "libp2p-crypto": "~0.17.0", + "libp2p-crypto": "~0.17.2", "multihashes": "~0.4.15", "protons": "^1.0.1" }, diff --git a/src/index.d.ts b/src/index.d.ts new file mode 100644 index 0000000..150997d --- /dev/null +++ b/src/index.d.ts @@ -0,0 +1,188 @@ +import crypto, { PrivateKey, PublicKey, KeyType } from "libp2p-crypto"; +import CID from 'cids' + +declare namespace PeerId { + /** + * Options for PeerId creation. + */ + type CreateOptions = { + /** + * The number of bits to use. + */ + bits?: number; + /** + * The type of key to use. + */ + keyType?: KeyType; + }; + + /** + * PeerId JSON format. + */ + type JSONPeerId = { + /** + * String representation of PeerId. + */ + id: string; + /** + * Public key. + */ + pubKey?: string; + /** + * Private key. + */ + privKey: string; + }; + + /** + * Checks if a value is an instance of PeerId. + * @param id The value to check. + */ + function isPeerId(id: any): boolean + + /** + * Create a new PeerId. + * @param opts Options. + */ + function create(opts?: PeerId.CreateOptions): Promise; + + /** + * Create PeerId from hex string. + * @param str The input hex string. + */ + function createFromHexString(str: string): PeerId; + + /** + * Create PeerId from raw bytes. + * @param buf The raw bytes. + */ + function createFromBytes(buf: Buffer): PeerId; + + /** + * Create PeerId from base58-encoded string. + * @param str The base58-encoded string. + */ + function createFromB58String(str: string): PeerId; + + /** + * Create PeerId from CID. + * @param cid The CID. + */ + function createFromCID(cid: CID | Buffer | string | object): PeerId; + + /** + * Create PeerId from public key. + * @param key Public key, as Buffer or base64-encoded string. + */ + function createFromPubKey(key: Buffer | string): Promise; + + /** + * Create PeerId from private key. + * @param key Private key, as Buffer or base64-encoded string. + */ + function createFromPrivKey(key: Buffer | string): Promise; + + /** + * Create PeerId from PeerId JSON formatted object. + * @see {@link PeerId#toJSON} + * @param json PeerId in JSON format. + */ + function createFromJSON(json: JSONPeerId): Promise; + + /** + * Create PeerId from Protobuf bytes. + * @param buf Protobuf bytes, as Buffer or hex-encoded string. + */ + function createFromProtobuf(buf: Buffer | string): Promise; +} + +/** + * PeerId is an object representation of a peer identifier. + */ +declare class PeerId { + constructor(id: Buffer | string, privKey?: PrivateKey, pubKey?: PublicKey); + + /** + * Raw id. + */ + id: Buffer; + + /** + * Private key. + */ + privKey: PrivateKey; + + /** + * Public key. + */ + pubKey: PublicKey; + + /** + * Return the protobuf version of the public key, matching go ipfs formatting. + */ + marshalPubKey(): Buffer; + + /** + * Return the protobuf version of the private key, matching go ipfs formatting. + */ + marshalPrivKey(): Buffer; + + /** + * Return the protobuf version of the peer-id. + * @param excludePriv Whether to exclude the private key information from the output. + */ + marshal(excludePriv?: boolean): Buffer; + + /** + * String representation. + */ + toPrint(): string; + + /** + * Return the jsonified version of the key. + * Matches the formatting of go-ipfs for its config file. + * @see {@link PeerId.createFromJSON} + */ + toJSON(): PeerId.JSONPeerId; + + /** + * Encode to hex. + */ + toHexString(): string; + + /** + * Return raw id bytes. + */ + toBytes(): Buffer; + + /** + * Encode to base58 string. + */ + toB58String(): string; + + /** + * Return self-describing string representation. + * Uses default format from RFC 0001: https://github.com/libp2p/specs/pull/209 + */ + toString(): string; + + /** + * Checks the equality of `this` peer against a given PeerId. + * @param id The other PeerId. + */ + equals(id: PeerId | Buffer): boolean; + + /** + * Checks the equality of `this` peer against a given PeerId. + * @deprecated Use {.equals} + * @param id The other PeerId. + */ + isEqual(id: PeerId | Buffer): boolean; + + /** + * Check if this PeerId instance is valid (privKey -> pubKey -> Id) + */ + isValid(): boolean; +} + +export = PeerId; diff --git a/test/peer-id.spec.js b/test/peer-id.spec.js index 8b48938..da55c45 100644 --- a/test/peer-id.spec.js +++ b/test/peer-id.spec.js @@ -271,24 +271,28 @@ describe('PeerId', () => { it('set privKey (valid)', async () => { const peerId = await PeerId.create(testOpts) + // @ts-ignore peerId.privKey = peerId._privKey expect(peerId.isValid()).to.equal(true) }) it('set pubKey (valid)', async () => { const peerId = await PeerId.create(testOpts) + // @ts-ignore peerId.pubKey = peerId._pubKey expect(peerId.isValid()).to.equal(true) }) it('set privKey (invalid)', async () => { const peerId = await PeerId.create(testOpts) + // @ts-ignore peerId.privKey = Buffer.from('bufff') expect(peerId.isValid()).to.equal(false) }) it('set pubKey (invalid)', async () => { const peerId = await PeerId.create(testOpts) + // @ts-ignore peerId.pubKey = Buffer.from('bufff') expect(peerId.isValid()).to.equal(false) }) diff --git a/tsconfig.json b/tsconfig.json new file mode 100644 index 0000000..b093bcc --- /dev/null +++ b/tsconfig.json @@ -0,0 +1,37 @@ +{ + "compilerOptions": { + "module": "commonjs", + "lib": [ + "es6" + ], + "target": "ES5", + "noImplicitAny": false, + "noImplicitThis": true, + "strictFunctionTypes": true, + "strictNullChecks": true, + "esModuleInterop": true, + "resolveJsonModule": true, + "allowJs": true, + "checkJs": true, + "baseUrl": ".", + "paths": { + "peer-id": [ + "./src", + "../src", + ] + }, + "types": [ + "node", + "mocha", + "chai" + ], + "noEmit": true, + "forceConsistentCasingInFileNames": true + }, + "files": [ + "./src/index.d.ts", + ], + "include": [ + "./test/**/*.spec.js" + ] +} \ No newline at end of file