Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

CID interface #161

Closed
wants to merge 23 commits into from
Closed

CID interface #161

Show file tree
Hide file tree
Changes from 19 commits
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
553bdee
feat: define sync multihash hasher interface
Gozala Jan 19, 2022
b677a65
chore: enable composite code path
Gozala Jan 19, 2022
655028b
feat: define CID as interface
Gozala Jan 19, 2022
5a976d0
Merge remote-tracking branch 'origin/master' into feat/cid-interface
Gozala Jan 19, 2022
9947c49
chore: add missing type params
Gozala Jan 19, 2022
3f2fafa
chore: remove unecessary exports
Gozala Jan 19, 2022
e841c28
chore: add clarifying comments
Gozala Jan 19, 2022
a306d52
fix: type errors
Gozala Jan 19, 2022
6da6273
chore: cleanup block module
Gozala Jan 19, 2022
88182b6
chore: remove uintented changes
Gozala Jan 19, 2022
99fcb43
chore: rename Algorithm to Alg
Gozala Jan 19, 2022
f624c80
chore: undo unintended change
Gozala Jan 19, 2022
aa6a478
chore: fix import
Gozala Jan 19, 2022
3c835a0
fix: revert CID class
Gozala Mar 30, 2022
6c92773
fix: add test to improve coverage
Gozala Mar 30, 2022
6e8b914
chore: merge master
Gozala Mar 30, 2022
680bd77
fix: add missing files
Gozala Mar 31, 2022
22d0fc0
fix: type errors
Gozala Mar 31, 2022
f21a1ba
Apply suggestions from code review
Gozala Mar 31, 2022
91f780e
merge upsteam changes
Gozala Jun 10, 2022
ec5e3d9
retain CID type info in Block impl
Gozala Jun 10, 2022
6023831
fix: type errors
Gozala Jun 10, 2022
7b36f00
try to fix typecheck
Gozala Jun 14, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
3 changes: 3 additions & 0 deletions package.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,9 @@
},
"./codecs/raw": {
"import": "./src/codecs/raw.js"
},
"./interface": {
"import": "./src/interface.js"
Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is so that one could import and use all the types as follows:

import * as API from 'multiformats/interface.js'

/**
 * @param {API.CID} cid
 */
export const test = (cid) => {
   // ...
}

Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

is there a case for exporting ./cid/interface since it's going to be quite common that this is all you want?

}
},
"devDependencies": {
Expand Down
83 changes: 25 additions & 58 deletions src/bases/base.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,20 +1,8 @@
import basex from '../../vendor/base-x.js'
import { coerce } from '../bytes.js'

/**
* @typedef {import('./interface').BaseEncoder} BaseEncoder
* @typedef {import('./interface').BaseDecoder} BaseDecoder
* @typedef {import('./interface').BaseCodec} BaseCodec
*/

/**
* @template {string} T
* @typedef {import('./interface').Multibase<T>} Multibase
*/
/**
* @template {string} T
* @typedef {import('./interface').MultibaseEncoder<T>} MultibaseEncoder
*/
// Linter can't see that API is used in types.
// eslint-disable-next-line
import * as API from './interface.js'

/**
* Class represents both BaseEncoder and MultibaseEncoder meaning it
Expand All @@ -23,8 +11,8 @@ import { coerce } from '../bytes.js'
* @class
* @template {string} Base
* @template {string} Prefix
* @implements {MultibaseEncoder<Prefix>}
* @implements {BaseEncoder}
* @implements {API.MultibaseEncoder<Prefix>}
* @implements {API.BaseEncoder}
*/
class Encoder {
/**
Expand All @@ -40,7 +28,7 @@ class Encoder {

/**
* @param {Uint8Array} bytes
* @returns {Multibase<Prefix>}
* @returns {API.Multibase<Prefix>}
*/
encode (bytes) {
if (bytes instanceof Uint8Array) {
Expand All @@ -51,29 +39,18 @@ class Encoder {
}
}

/**
* @template {string} Prefix
* @typedef {import('./interface').MultibaseDecoder<Prefix>} MultibaseDecoder
*/

/**
* @template {string} Prefix
* @typedef {import('./interface').UnibaseDecoder<Prefix>} UnibaseDecoder
*/

/**
* @template {string} Prefix
*/
/**
* Class represents both BaseDecoder and MultibaseDecoder so it could be used
* to decode multibases (with matching prefix) or just base decode strings
* with corresponding base encoding.
* @class
* @template {string} Base
* @template {string} Prefix
* @implements {MultibaseDecoder<Prefix>}
* @implements {UnibaseDecoder<Prefix>}
* @implements {BaseDecoder}
* @implements {API.MultibaseDecoder<Prefix>}
* @implements {API.UnibaseDecoder<Prefix>}
* @implements {API.BaseDecoder}
*/
class Decoder {
/**
Expand Down Expand Up @@ -107,7 +84,7 @@ class Decoder {

/**
* @template {string} OtherPrefix
* @param {UnibaseDecoder<OtherPrefix>|ComposedDecoder<OtherPrefix>} decoder
* @param {API.UnibaseDecoder<OtherPrefix>|ComposedDecoder<OtherPrefix>} decoder
* @returns {ComposedDecoder<Prefix|OtherPrefix>}
*/
or (decoder) {
Expand All @@ -117,30 +94,25 @@ class Decoder {

/**
* @template {string} Prefix
* @typedef {import('./interface').CombobaseDecoder<Prefix>} CombobaseDecoder
*/

/**
* @template {string} Prefix
* @typedef {Record<Prefix, UnibaseDecoder<Prefix>>} Decoders
* @typedef {Record<Prefix, API.UnibaseDecoder<Prefix>>} Decoders
*/

/**
* @template {string} Prefix
* @implements {MultibaseDecoder<Prefix>}
* @implements {CombobaseDecoder<Prefix>}
* @implements {API.MultibaseDecoder<Prefix>}
* @implements {API.CombobaseDecoder<Prefix>}
*/
class ComposedDecoder {
/**
* @param {Record<Prefix, UnibaseDecoder<Prefix>>} decoders
* @param {Decoders<Prefix>} decoders
*/
constructor (decoders) {
this.decoders = decoders
}

/**
* @template {string} OtherPrefix
* @param {UnibaseDecoder<OtherPrefix>|ComposedDecoder<OtherPrefix>} decoder
* @param {API.UnibaseDecoder<OtherPrefix>|ComposedDecoder<OtherPrefix>} decoder
* @returns {ComposedDecoder<Prefix|OtherPrefix>}
*/
or (decoder) {
Expand All @@ -165,30 +137,25 @@ class ComposedDecoder {
/**
* @template {string} L
* @template {string} R
* @param {UnibaseDecoder<L>|CombobaseDecoder<L>} left
* @param {UnibaseDecoder<R>|CombobaseDecoder<R>} right
* @param {API.UnibaseDecoder<L>|API.CombobaseDecoder<L>} left
* @param {API.UnibaseDecoder<R>|API.CombobaseDecoder<R>} right
* @returns {ComposedDecoder<L|R>}
*/
export const or = (left, right) => new ComposedDecoder(/** @type {Decoders<L|R>} */({
...(left.decoders || { [/** @type UnibaseDecoder<L> */(left).prefix]: left }),
...(right.decoders || { [/** @type UnibaseDecoder<R> */(right).prefix]: right })
...(left.decoders || { [/** @type API.UnibaseDecoder<L> */(left).prefix]: left }),
...(right.decoders || { [/** @type API.UnibaseDecoder<R> */(right).prefix]: right })
}))

/**
* @template T
* @typedef {import('./interface').MultibaseCodec<T>} MultibaseCodec
*/

/**
* @class
* @template {string} Base
* @template {string} Prefix
* @implements {MultibaseCodec<Prefix>}
* @implements {MultibaseEncoder<Prefix>}
* @implements {MultibaseDecoder<Prefix>}
* @implements {BaseCodec}
* @implements {BaseEncoder}
* @implements {BaseDecoder}
* @implements {API.MultibaseCodec<Prefix>}
* @implements {API.MultibaseEncoder<Prefix>}
* @implements {API.MultibaseDecoder<Prefix>}
* @implements {API.BaseCodec}
* @implements {API.BaseEncoder}
* @implements {API.BaseDecoder}
*/
export class Codec {
/**
Expand Down
1 change: 1 addition & 0 deletions src/bases/interface.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1 @@
// this is dummy module overlayed by interface.ts
59 changes: 20 additions & 39 deletions src/block.js
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,4 +1,7 @@
import { bytes as binary, CID } from './index.js'
// Linter can see that API is used in types.
// eslint-disable-next-line
import * as API from './interface.js'

const readonly = ({ enumerable = true, configurable = false } = {}) => ({
enumerable,
Expand Down Expand Up @@ -94,14 +97,14 @@ const get = (source, path) => {
class Block {
/**
* @param {Object} options
* @param {CID} options.cid
* @param {ByteView<T>} options.bytes
* @param {API.CID} options.cid
* @param {API.ByteView<T>} options.bytes
* @param {T} options.value
*/
constructor ({ cid, bytes, value }) {
if (!cid || !bytes || typeof value === 'undefined') throw new Error('Missing required argument')

this.cid = cid
this.cid = /** @type {CID} */(cid)
this.bytes = bytes
this.value = value
this.asBlock = this
Expand Down Expand Up @@ -134,11 +137,11 @@ class Block {
/**
* @template T
* @template {number} Code
* @template {number} Algorithm
* @template {number} Alg
* @param {Object} options
* @param {T} options.value
* @param {BlockEncoder<Code, T>} options.codec
* @param {Hasher<Algorithm>} options.hasher
* @param {API.BlockEncoder<Code, T>} options.codec
* @param {API.MultihashHasher<Alg>} options.hasher
* @returns {Promise<Block<T>>}
*/
const encode = async ({ value, codec, hasher }) => {
Expand All @@ -155,11 +158,11 @@ const encode = async ({ value, codec, hasher }) => {
/**
* @template T
* @template {number} Code
* @template {number} Algorithm
* @template {number} Alg
* @param {Object} options
* @param {ByteView<T>} options.bytes
* @param {BlockDecoder<Code, T>} options.codec
* @param {Hasher<Algorithm>} options.hasher
* @param {API.ByteView<T>} options.bytes
* @param {API.BlockDecoder<Code, T>} options.codec
* @param {API.MultihashHasher<Alg>} options.hasher
* @returns {Promise<Block<T>>}
*/
const decode = async ({ bytes, codec, hasher }) => {
Expand All @@ -175,13 +178,13 @@ const decode = async ({ bytes, codec, hasher }) => {

/**
* @typedef {Object} RequiredCreateOptions
* @property {CID} options.cid
* @property {API.CID} options.cid
*/

/**
* @template T
* @template {number} Code
* @param {{ cid: CID, value:T, codec?: BlockDecoder<Code, T>, bytes: ByteView<T> }|{cid:CID, bytes:ByteView<T>, value?:void, codec:BlockDecoder<Code, T>}} options
* @param {{ cid: API.CID, value:T, codec?: API.BlockDecoder<Code, T>, bytes: API.ByteView<T> }|{cid:API.CID, bytes:API.ByteView<T>, value?:void, codec:API.BlockDecoder<Code, T>}} options
* @returns {Block<T>}
*/
const createUnsafe = ({ bytes, cid, value: maybeValue, codec }) => {
Expand All @@ -197,12 +200,12 @@ const createUnsafe = ({ bytes, cid, value: maybeValue, codec }) => {
/**
* @template T
* @template {number} Code
* @template {number} Algorithm
* @template {number} Alg
* @param {Object} options
* @param {CID} options.cid
* @param {ByteView<T>} options.bytes
* @param {BlockDecoder<Code, T>} options.codec
* @param {Hasher<Algorithm>} options.hasher
* @param {API.CID<Code, Alg>} options.cid
* @param {API.ByteView<T>} options.bytes
* @param {API.BlockDecoder<Code, T>} options.codec
* @param {API.MultihashHasher<Alg>} options.hasher
* @returns {Promise<Block<T>>}
*/
const create = async ({ bytes, cid, hasher, codec }) => {
Expand All @@ -218,25 +221,3 @@ const create = async ({ bytes, cid, hasher, codec }) => {
}

export { encode, decode, create, createUnsafe, Block }

/**
* @template T
* @typedef {import('./codecs/interface').ByteView<T>} ByteView
*/

/**
* @template {number} Code
* @template T
* @typedef {import('./codecs/interface').BlockEncoder<Code, T>} BlockEncoder
*/

/**
* @template {number} Code
* @template T
* @typedef {import('./codecs/interface').BlockDecoder<Code, T>} BlockDecoder
*/

/**
* @template Algorithm
* @typedef {import('./hashes/interface').MultihashHasher} Hasher
*/
Loading