From eeb7e8d3634ccc337b94d015b91c7105adc9670d Mon Sep 17 00:00:00 2001
From: Hayden Young <haydenyoung@wijiti.com>
Date: Tue, 27 Jun 2023 21:51:26 +0100
Subject: [PATCH] docs: Type defs for returned objects.
---
src/address.js | 17 ++++++++++++++---
src/identities/identity.js | 19 +++++++++++--------
2 files changed, 25 insertions(+), 11 deletions(-)
diff --git a/src/address.js b/src/address.js
index f942c1d..4ed87de 100644
--- a/src/address.js
+++ b/src/address.js
@@ -9,7 +9,7 @@ import { posixJoin } from './utils/path-join.js'
/**
* Validates an OrbitDB database address.
* @function
- * @param {OrbitDBAddress|string} address An OrbitDB database address.
+ * @param {module:Address~OrbitDBAddress|string} address An OrbitDB database address.
* @return {boolean} True if the address is a valid OrbitDB database address,
* false otherwise.
* @static
@@ -39,8 +39,8 @@ const isValidAddress = (address) => {
/**
* Parses an OrbitDB database address.
* @function
- * @param {OrbitDBAddress|string} address A valid OrbitDB database address.
- * @return {OrbitDBAddress} An instance of OrbitDBAddress.
+ * @param {module:Address~OrbitDBAddress|string} address A valid OrbitDB database address.
+ * @return {module:Address~OrbitDBAddress} An instance of OrbitDBAddress.
* @throws Not a valid OrbitDB address if no address if provided.
* @throws Not a valid OrbitDB address if address is invalid.
* @static
@@ -57,6 +57,12 @@ const parseAddress = (address) => {
return OrbitDBAddress(address)
}
+/**
+ * @typedef {Object} OrbitDBAddress
+ * @property {string} protocol The address protocol (/orbitdb/).
+ * @property {string} hash The hash of the database.
+ * @property {string} address The full database address.
+ */
const OrbitDBAddress = (address) => {
if (address && address.protocol === 'orbitdb' && address.hash) {
return address
@@ -66,6 +72,11 @@ const OrbitDBAddress = (address) => {
const hash = address.replace('/orbitdb/', '').replace('\\orbitdb\\', '')
+ /**
+ * Returns address as a string.
+ * @typedef {Function} toString
+ * @returns {string} Address as a string.
+ */
const toString = () => {
return posixJoin('/', protocol, hash)
}
diff --git a/src/identities/identity.js b/src/identities/identity.js
index e485b60..8290563 100644
--- a/src/identities/identity.js
+++ b/src/identities/identity.js
@@ -7,19 +7,20 @@ const codec = dagCbor
const hasher = sha256
const hashStringEncoding = base58btc
+/**
+ * @typedef {Object} module:Identities~Identity
+ * @property {string} id A unique identifer for the identity.
+ * @property {object} publicKey A public key.
+ * @property {object} signatures A signed identity id and public key.
+ * @property {string} type The type of identity provider.
+ * @property {function} sign A sign function.
+ * @property {function} verify A verify function.
+ */
const Identity = async ({ id, publicKey, signatures, type, sign, verify } = {}) => {
/**
* @namespace module:Identities~Identity
* @description The Identity instance. Returned by
* [Identities.createIdentity()]{@link module:Identities~Identities#createIdentity}.
- *
- * Available Identity instance properties and functions are:
- * - **id:** A unique identifer for the identity.
- * - **publicKey:** A public key.
- * - **signatures:** A signed identity id and public key.
- * - **type:** The type of identity provider.
- * - **sign:** A sign function.
- * - **verify:** A verify function.
*/
if (!id) throw new Error('Identity id is required')
if (!publicKey) throw new Error('Invalid public key')
@@ -64,6 +65,7 @@ const decodeIdentity = async (bytes) => {
* @param {Identity} identity The identity to verify.
* @return {boolean} True if the identity is valid, false otherwise.
* @static
+ * @private
*/
const isIdentity = (identity) => {
return Boolean(identity.id &&
@@ -82,6 +84,7 @@ const isIdentity = (identity) => {
* @param {Identity} b Second identity.
* @return {boolean} True if identity a and b are equal, false otherwise.
* @static
+ * @private
*/
const isEqual = (a, b) => {
return a.id === b.id &&