docs: update api docs

README.md

@@ -14,19 +14,11 @@
 - [Usage](#usage)
   - [Create record](#create-record)
   - [Validate record](#validate-record)
-  - [Embed public key to record](#embed-public-key-to-record)
   - [Extract public key from record](#extract-public-key-from-record)
   - [Marshal data with proto buffer](#marshal-data-with-proto-buffer)
   - [Unmarshal data from proto buffer](#unmarshal-data-from-proto-buffer)
-  - [Validator](#validator)
-- [API](#api)
-  - [Create record](#create-record-1)
-  - [Validate record](#validate-record-1)
-  - [Marshal data with proto buffer](#marshal-data-with-proto-buffer-1)
-  - [Unmarshal data from proto buffer](#unmarshal-data-from-proto-buffer-1)
-  - [Extract public key from record](#extract-public-key-from-record-1)
-  - [Namespace](#namespace)
 - [API Docs](#api-docs)
+  - [Namespace](#namespace)
 - [License](#license)
 - [Contribute](#contribute)
 
@@ -53,42 +45,34 @@ This module contains all the necessary code for creating, understanding and vali
 ```js
 import * as ipns from 'ipns'
 
-const ipnsRecord = await ipns.create(privateKey, value, sequenceNumber, lifetime)
+const ipnsRecord = await ipns.createIPNSRecord(privateKey, value, sequenceNumber, lifetime)
 ```
 
 ### Validate record
 
 ```js
-import * as ipns from 'ipns'
+import { validate } from 'ipns/validator'
 
-await ipns.validate(publicKey, marshalledData)
+await validate(publicKey, marshalledData)
 // if no error thrown, the record is valid
 ```
 
-### Embed public key to record
-
-```js
-import * as ipns from 'ipns'
-
-const ipnsRecordWithEmbeddedPublicKey = await ipns.embedPublicKey(publicKey, ipnsRecord)
-```
-
 ### Extract public key from record
 
 ```js
 import * as ipns from 'ipns'
 
-const publicKey = await ipns.extractPublicKey(peerId, ipnsRecord)
+const publicKey = await ipns.extractPublicKeyFromIPNSRecord(peerId, ipnsRecord)
 ```
 
 ### Marshal data with proto buffer
 
 ```js
 import * as ipns from 'ipns'
 
-const ipnsRecord = await ipns.create(privateKey, value, sequenceNumber, lifetime)
+const ipnsRecord = await ipns.createIPNSRecord(privateKey, value, sequenceNumber, lifetime)
 // ...
-const marshalledData = ipns.marshal(ipnsRecord)
+const marshalledData = ipns.marshalIPNSRecord(ipnsRecord)
 // ...
 ```
 
@@ -99,89 +83,16 @@ Returns the record data serialized.
 ```js
 import * as ipns from 'ipns'
 
-const ipnsRecord = ipns.unmarshal(storedData)
+const ipnsRecord = ipns.unmarshalIPNSRecord(storedData)
 ```
 
 Returns the `IPNSRecord` after being deserialized.
 
-### Validator
-
-```js
-import * as ipns from 'ipns'
-
-const validator = ipns.validator
-```
-
-Contains an object with `validate (marshalledData, key)` and `select (dataA, dataB)` functions.
 
-The `validate` async function aims to verify if an IPNS record is valid. First the record is unmarshalled, then the public key is obtained and finally the record is validated (`signatureV2` of CBOR `data` is verified).
-
-The `select` function is responsible for deciding which IPNS record is the best (newer) between two records. Both records are unmarshalled and their sequence numbers are compared. If the first record provided is the newer, the operation result will be `0`, otherwise the operation result will be `1`.
-
-## API
-
-### Create record
-
-```js
-
-ipns.create(privateKey, value, sequenceNumber, lifetime, options)
-```
-
-Create an IPNS record for being stored in a protocol buffer.
-
-- `privateKey` ([PrivateKey](https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.keys.PrivateKey.html)): key to be used for cryptographic operations.
-- `value` (string): IPFS path of the object to be published.
-- `sequenceNumber` (Number): number representing the current version of the record.
-- `lifetime` (Number): lifetime of the record (in milliseconds).
-- `options` (CreateOptions): additional creation options.
-
-Returns a `Promise` that resolves to an object with a `IPNSRecord`.
-
-### Validate record
-
-```js
-ipns.validate(publicKey, ipnsRecord)
-```
-
-Validate an IPNS record previously stored in a protocol buffer.
-
-- `publicKey` ([PublicKey](https://libp2p.github.io/js-libp2p/interfaces/_libp2p_interface.keys.PublicKey.html)): key to be used for cryptographic operations.
-- `ipnsRecord` (`IPNSRecord`): IPNS record (obtained using the create function).
-
-Returns a `Promise`, which may be rejected if the validation was not successful.
-
-### Marshal data with proto buffer
-
-```js
-const marshalledData = ipns.marshal(ipnsRecord)
-```
-
-Returns the serialized IPNS record.
-
-- `ipnsRecord` (`IPNSRecord`): ipns record (obtained using the create function).
-
-### Unmarshal data from proto buffer
-
-```js
-const data = ipns.unmarshal(storedData)
-```
-
-Returns a `IPNSRecord` after being serialized.
-
-- `storedData` (Uint8Array): ipns record serialized.
-
-### Extract public key from record
-
-```js
-const publicKey = await ipns.extractPublicKey(peerId, ipnsRecord)
-```
-
-Extract a public key from an IPNS record.
+## API Docs
 
-- `peerId` ([PeerId](https://libp2p.github.io/js-libp2p/types/_libp2p_interface.peer_id.PeerId.html)): peer identifier object.
-- `ipnsRecord` (`IPNSRecord`): ipns record (obtained using the create function).
+- <https://ipfs.github.io/js-ipns>
 
-Returns a `Promise` which resolves to public key ([`PublicKey`](https://github.com/libp2p/js-libp2p-interfaces/blob/master/packages/interface-keys/src/index.ts) ): may be used for cryptographic operations.
 
 ### Namespace
 
@@ -199,9 +110,6 @@ ipns.namespaceLength
 // 6
 ```
 
-## API Docs
-
-- <https://ipfs.github.io/js-ipns>
 
 ## License
 

src/index.ts

@@ -146,10 +146,10 @@ const defaultCreateOptions: CreateOptions = {
  * The IPNS Record validity should follow the [RFC3339]{@link https://www.ietf.org/rfc/rfc3339.txt} with nanoseconds precision.
  * Note: This function does not embed the public key. If you want to do that, use `EmbedPublicKey`.
  *
- * The passed value can be a CID, a PeerID or an arbitrary string path.
+ * The passed value can be a CID, a PublicKey or an arbitrary string path e.g. `/ipfs/...` or `/ipns/...`.
  *
  * * CIDs will be converted to v1 and stored in the record as a string similar to: `/ipfs/${cid}`
- * * PeerIDs will create recursive records, eg. the record value will be `/ipns/${cidV1Libp2pKey}`
+ * * PublicKeys will create recursive records, eg. the record value will be `/ipns/${cidV1Libp2pKey}`
  * * String paths will be stored in the record as-is, but they must start with `"/"`
  *
  * @param {PrivateKey} privateKey - the private key for signing the record.
@@ -174,10 +174,10 @@ export async function createIPNSRecord (privateKey: PrivateKey, value: CID | Pub
  * Same as create(), but instead of generating a new Date, it receives the intended expiration time
  * WARNING: nano precision is not standard, make sure the value in seconds is 9 orders of magnitude lesser than the one provided.
  *
- * The passed value can be a CID, a PeerID or an arbitrary string path.
+ * The passed value can be a CID, a PublicKey or an arbitrary string path e.g. `/ipfs/...` or `/ipns/...`.
  *
  * * CIDs will be converted to v1 and stored in the record as a string similar to: `/ipfs/${cid}`
- * * PeerIDs will create recursive records, eg. the record value will be `/ipns/${cidV1Libp2pKey}`
+ * * PublicKeys will create recursive records, eg. the record value will be `/ipns/${cidV1Libp2pKey}`
  * * String paths will be stored in the record as-is, but they must start with `"/"`
  *
  * @param {PrivateKey} privateKey - the private key for signing the record.

src/selector.ts

@@ -2,6 +2,18 @@ import NanoDate from 'timestamp-nano'
 import { IpnsEntry } from './pb/ipns.js'
 import { unmarshalIPNSRecord } from './utils.js'
 
+/**
+ * Selects the most latest valid IPNS record from an array of marshalled IPNS records.
+ *
+ * Records are sorted by:
+ * 1. Sequence number (higher takes precedence)
+ * 2. Validity time for EOL records with same sequence number (longer lived record takes precedence)
+ *
+ * @param key - The routing key for the IPNS record
+ * @param data - Array of marshalled IPNS records to select from
+ * @returns The index of the most valid record from the input array
+ */
+
 export function ipnsSelector (key: Uint8Array, data: Uint8Array[]): number {
   const entries = data.map((buf, index) => ({
     record: unmarshalIPNSRecord(buf),

test/utils.spec.ts

@@ -22,6 +22,16 @@ describe('utils', () => {
         output: '/ipns/k73ap3wtp70r7cd9ofyhwgogv1j96huvtvfnsof5spyfaaopkxmonumi4fckgguqr'
       },
 
+      // path input
+      '/ipfs/CID path': {
+        input: '/ipfs/QmWEekX7EZLUd9VXRNMRXW3LXe4F6x7mB8oPxY5XLptrBq/docs/readme.md',
+        output: '/ipfs/QmWEekX7EZLUd9VXRNMRXW3LXe4F6x7mB8oPxY5XLptrBq/docs/readme.md'
+      },
+      '/ipns/CID path': {
+        input: '/ipns/k51qzi5uqu5djni72pr40dt64kxlh0zb8baat8h7dtdvkov66euc2lho0oidr3',
+        output: '/ipns/k51qzi5uqu5djni72pr40dt64kxlh0zb8baat8h7dtdvkov66euc2lho0oidr3'
+      },
+
       // peer id input
       'Ed25519 PeerId': {
         input: peerIdFromString('12D3KooWKBpVwnRACfEsk6QME7dA5CZnFYVHQ7Zc927BEzuUekQe'),