\href{https://github.com/zkat/protoduck}{\texttt{ {\ttfamily protoduck}}} is a Java\+Script library is a library for making groups of methods, called \char`\"{}protocols\char`\"{}.

If you\textquotesingle{}re familiar with the concept of \href{https://en.wikipedia.org/wiki/Duck_typing}{\texttt{ \char`\"{}duck typing\char`\"{}}}, then it might make sense to think of protocols as things that explicitly define what methods you need in order to \char`\"{}clearly be a duck\char`\"{}.\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22308}{}\doxysection{Install}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22308}
{\ttfamily \$ npm install -\/S protoduck}\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22309}{}\doxysection{Table of Contents}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22309}

\begin{DoxyItemize}
\item \href{\#example}{\texttt{ Example}}
\item \href{\#features}{\texttt{ Features}}
\item \href{\#guide}{\texttt{ Guide}}
\begin{DoxyItemize}
\item \href{\#introduction}{\texttt{ Introduction}}
\item \href{\#defining-protocols}{\texttt{ Defining protocols}}
\item \href{\#protocol-impls}{\texttt{ Implementations}}
\item \href{\#multiple-dispatch}{\texttt{ Multiple dispatch}}
\item \href{\#constraints}{\texttt{ Constraints}}
\end{DoxyItemize}
\item \href{\#api}{\texttt{ API}}
\begin{DoxyItemize}
\item \href{\#define}{\texttt{ {\ttfamily define()}}}
\item \href{\#impl}{\texttt{ {\ttfamily proto.\+impl()}}}
\end{DoxyItemize}
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22310}{}\doxysubsection{Example}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22310}

\begin{DoxyCode}{0}
\DoxyCodeLine{const protoduck = require('protoduck')}
\DoxyCodeLine{}
\DoxyCodeLine{// Quackable is a protocol that defines three methods}
\DoxyCodeLine{const Quackable = protoduck.define(\{}
\DoxyCodeLine{  walk: [],}
\DoxyCodeLine{  talk: [],}
\DoxyCodeLine{  isADuck: [() => true] // default implementation -\/-\/ it's optional!}
\DoxyCodeLine{\})}
\DoxyCodeLine{}
\DoxyCodeLine{// `duck` must implement `Quackable` for this function to work. It doesn't}
\DoxyCodeLine{// matter what type or class duck is, as long as it implements Quackable.}
\DoxyCodeLine{function doStuffToDucks (duck) \{}
\DoxyCodeLine{  if (!duck.isADuck()) \{}
\DoxyCodeLine{    throw new Error('I want a duck!')}
\DoxyCodeLine{  \} else \{}
\DoxyCodeLine{    console.log(duck.walk())}
\DoxyCodeLine{    console.log(duck.talk())}
\DoxyCodeLine{  \}}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{// ...In a different package:}
\DoxyCodeLine{const ducks = require('./ducks')}
\DoxyCodeLine{}
\DoxyCodeLine{class Duck () \{\}}
\DoxyCodeLine{}
\DoxyCodeLine{// Implement the protocol on the Duck class.}
\DoxyCodeLine{ducks.Quackable.impl(Duck, \{}
\DoxyCodeLine{  walk () \{ return "{}*hobble hobble*"{} \}}
\DoxyCodeLine{  talk () \{ return "{}QUACK QUACK"{} \}}
\DoxyCodeLine{\})}
\DoxyCodeLine{}
\DoxyCodeLine{// main.js}
\DoxyCodeLine{ducks.doStuffToDucks(new Duck()) // works! }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22311}{}\doxysubsection{Features}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22311}

\begin{DoxyItemize}
\item Verifies implementations in case methods are missing or wrong ones added
\item Helpful, informative error messages
\item Optional default method implementations
\item Fresh Java\+Script Feel™ -- methods work just like native methods when called
\item Methods can dispatch on arguments, not just {\ttfamily this} (\href{https://npm.im/genfun}{\texttt{ multimethods}})
\item Type constraints
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22312}{}\doxysubsection{Guide}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22312}
\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22313}{}\doxysubsubsection{Introduction}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22313}
Like most Object-\/oriented languages, Java\+Script comes with its own way of defining methods\+: You simply add regular {\ttfamily function}s as properties to regular objects, and when you do {\ttfamily obj.\+method()}, it calls the right code! ES6/\+ES2015 further extended this by adding a {\ttfamily class} syntax that allowed this same system to work with more familiar syntax sugar\+: {\ttfamily class Foo \{ method() \{ ... \} \}}.

The point of \char`\"{}protocols\char`\"{} is to have a more explicit definitions of what methods \char`\"{}go together\char`\"{}. That is, a protocol is a description of a type of object your code interacts with. If someone passes an object into your library, and it fits your defined protocol, the assumption is that the object will work just as well.

Duck typing is a common term for this sort of thing\+: If it walks like a duck, and it talks like a duck, then it may as well be a duck, as far as any of our code is concerned.

Many other languages have similar or identical concepts under different names\+: Java\textquotesingle{}s interfaces, Haskell\textquotesingle{}s typeclasses, Rust\textquotesingle{}s traits. Elixir and Clojure both call them \char`\"{}protocols\char`\"{} as well.

One big advantage to using these protocols is that they let users define their own versions of some abstraction, without requiring the type to inherit from another -- protocols are independent of inheritance, even though they\textquotesingle{}re able to work together with it. If you\textquotesingle{}ve ever found yourself in some sort of inheritance mess, this is exactly the sort of thing you use to escape it.\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22314}{}\doxysubsubsection{Defining Protocols}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22314}
The first step to using {\ttfamily protoduck} is to define a protocol. Protocol definitions look like this\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{// import the library first!}
\DoxyCodeLine{const protoduck = require('protoduck')}
\DoxyCodeLine{}
\DoxyCodeLine{// `Ducklike` is the name of our protocol. It defines what it means for}
\DoxyCodeLine{// something to be "{}like a duck"{}, as far as our code is concerned.}
\DoxyCodeLine{const Ducklike = protoduck.define([], \{}
\DoxyCodeLine{  walk: [], // This says that the protocol requires a "{}walk"{} method.}
\DoxyCodeLine{  talk: [] // and ducks also need to talk}
\DoxyCodeLine{  peck: [] // and they can even be pretty scary}
\DoxyCodeLine{\}) }

\end{DoxyCode}


Protocols by themselves don\textquotesingle{}t really {\itshape do} anything, they simply define what methods are included in the protocol, and thus what will need to be implemented.\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22315}{}\doxysubsubsection{Protocol Impls}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22315}
The simplest type of definitions for protocols are as regular methods. In this style, protocols end up working exactly like normal Java\+Script methods\+: they\textquotesingle{}re added as properties of the target type/object, and we call them using the {\ttfamily foo.\+method()} syntax. {\ttfamily this} is accessible inside the methods, as usual.

Implementation syntax is very similar to protocol definitions, using {\ttfamily .impl}\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{class Dog \{\}}
\DoxyCodeLine{}
\DoxyCodeLine{// Implementing `Ducklike` for `Dog`s}
\DoxyCodeLine{Ducklike.impl(Dog, [], \{}
\DoxyCodeLine{  walk () \{ return '*pads on all fours*' \}}
\DoxyCodeLine{  talk () \{ return 'woof woof. I mean "{}quack"{} >\_>' \}}
\DoxyCodeLine{  peck (victim) \{ return 'Can I just bite ' + victim + ' instead?...' \}}
\DoxyCodeLine{\}) }

\end{DoxyCode}


So now, our {\ttfamily Dog} class has two extra methods\+: {\ttfamily walk}, and {\ttfamily talk}, and we can just call them\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{const pupper = new Dog()}
\DoxyCodeLine{}
\DoxyCodeLine{pupper.walk() // *pads on all fours*}
\DoxyCodeLine{pupper.talk() // woof woof. I mean "{}quack"{} >\_>}
\DoxyCodeLine{pupper.peck('this string') // Can I just bite this string instead?... }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22316}{}\doxysubsubsection{Multiple Dispatch}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22316}
You may have noticed before that we have these {\ttfamily \mbox{[}\mbox{]}} in various places that don\textquotesingle{}t seem to have any obvious purpose.

These arrays allow protocols to be implemented not just for a single value of {\ttfamily this}, but across {\itshape all arguments}. That is, you can have methods in these protocols that use both {\ttfamily this}, and the first argument (or any other arguments) in order to determine what code to actually execute.

This type of method is called a multimethod, and is one of the differences between protoduck and the default {\ttfamily class} syntax.

To use it\+: in the protocol {\itshape definitions}, you put matching strings in different spots where those empty arrays were, and when you {\itshape implement} the protocol, you give the definition the actual types/objects you want to implement it on, and it takes care of mapping types to the strings you defined, and making sure the right code is run\+:


\begin{DoxyCode}{0}
\DoxyCodeLine{const Playful = protoduck.define(['friend'], \{// <-\/-\/-\/\(\backslash\)}
\DoxyCodeLine{  playWith: ['friend'] // <-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/-\/ these correspond to each other}
\DoxyCodeLine{\})}
\DoxyCodeLine{}
\DoxyCodeLine{class Cat \{\}}
\DoxyCodeLine{class Human \{\}}
\DoxyCodeLine{class Dog \{\}}
\DoxyCodeLine{}
\DoxyCodeLine{// The first protocol is for Cat/Human combination}
\DoxyCodeLine{Playful.impl(Cat, [Human], \{}
\DoxyCodeLine{  playWith (human) \{}
\DoxyCodeLine{    return '*headbutt* *purr* *cuddle* omg ilu, ' + human.name}
\DoxyCodeLine{  \}}
\DoxyCodeLine{\})}
\DoxyCodeLine{}
\DoxyCodeLine{// And we define it *again* for a different combination}
\DoxyCodeLine{Playful.impl(Cat, [Dog], \{}
\DoxyCodeLine{  playWith (dog) \{}
\DoxyCodeLine{    return '*scratches* *hisses* omg i h8 u, ' + dog.name}
\DoxyCodeLine{  \}}
\DoxyCodeLine{\})}
\DoxyCodeLine{}
\DoxyCodeLine{// depending on what you call it with, it runs different methods:}
\DoxyCodeLine{const cat = new Cat()}
\DoxyCodeLine{const human = new Human()}
\DoxyCodeLine{const dog = new Dog()}
\DoxyCodeLine{}
\DoxyCodeLine{cat.playWith(human) // *headbutt* *purr* *cuddle* omg ilu, Sam}
\DoxyCodeLine{cat.playWith(dog) // *scratches* *hisses* omg i h8 u, Pupper }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22317}{}\doxysubsubsection{Constraints}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22317}
Sometimes, you want to have all the functionality of a certain protocol, but you want to add a few requirements or other bits an pieces. Usually, you would have to define the entire functionality of the \char`\"{}parent\char`\"{} protocol in your own protocol in order to pull this off. This isn\textquotesingle{}t very DRY and thus prone to errors, missing or out-\/of-\/sync functionality, or other issues. You could also just tell users \char`\"{}hey, if you implement this, make sure to implement that\char`\"{}, but there\textquotesingle{}s no guarantee they\textquotesingle{}ll know about it, or know which arguments map to what.

This is where constraints come in\+: You can define a protocol that expects anything that implements it to {\itshape also} implement one or more \char`\"{}parent\char`\"{} protocols.


\begin{DoxyCode}{0}
\DoxyCodeLine{const Show = proto.define(\{}
\DoxyCodeLine{  // This syntax allows default impls without using arrays.}
\DoxyCodeLine{  toString () \{}
\DoxyCodeLine{    return Object.prototype.toString.call(this)}
\DoxyCodeLine{  \},}
\DoxyCodeLine{  toJSON () \{}
\DoxyCodeLine{    return JSON.stringify(this)}
\DoxyCodeLine{  \}}
\DoxyCodeLine{\})}
\DoxyCodeLine{}
\DoxyCodeLine{const Log = proto.define(\{}
\DoxyCodeLine{  log () \{ console.log(this.toString()) \}}
\DoxyCodeLine{\}, \{}
\DoxyCodeLine{  where: Show()}
\DoxyCodeLine{  // Also valid:}
\DoxyCodeLine{  // [Show('this'), Show('a')]}
\DoxyCodeLine{  // [Show('this', ['a', 'b'])]}
\DoxyCodeLine{\})}
\DoxyCodeLine{}
\DoxyCodeLine{// This fails with an error: must implement Show:}
\DoxyCodeLine{Log.impl(MyThing)}
\DoxyCodeLine{}
\DoxyCodeLine{// So derive Show first...}
\DoxyCodeLine{Show.impl(MyThing)}
\DoxyCodeLine{// And now it's ok!}
\DoxyCodeLine{Log.impl(MyThing) }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22318}{}\doxysubsection{API}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22318}
\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22319}{}\doxysubsubsection{$<$a name=\char`\"{}define\char`\"{}$>$$<$/a$>$ $<$tt$>$define($<$types$>$?, $<$spec$>$, $<$opts$>$)$<$/tt$>$}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22319}
Defines a new protocol on across arguments of types defined by {\ttfamily $<$types$>$}, which will expect implementations for the functions specified in {\ttfamily $<$spec$>$}.

If {\ttfamily $<$types$>$} is missing, it will be treated the same as if it were an empty array.

The types in {\ttfamily $<$spec$>$} entries must map, by string name, to the type names specified in {\ttfamily $<$types$>$}, or be an empty array if {\ttfamily $<$types$>$} is omitted. The types in {\ttfamily $<$spec$>$} will then be used to map between method implementations for the individual functions, and the provided types in the impl.

Protocols can include an {\ttfamily opts} object as the last argument, with the following available options\+:


\begin{DoxyItemize}
\item {\ttfamily opts.\+name} {\ttfamily \{String\}} -\/ The name to use when referring to the protocol.
\item {\ttfamily opts.\+where} {\ttfamily \{Array\mbox{[}Constraint\mbox{]}$\vert$\+Constraint\}} -\/ Protocol constraints to use.
\item {\ttfamily opts.\+metaobject} -\/ Accepts an object implementing the {\ttfamily Protoduck} protocol, which can be used to alter protocol definition mechanisms in {\ttfamily protoduck}.
\end{DoxyItemize}\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22320}{}\doxyparagraph{Example}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22320}

\begin{DoxyCode}{0}
\DoxyCodeLine{const Eq = protoduck.define(['a'], \{}
\DoxyCodeLine{  eq: ['a']}
\DoxyCodeLine{\}) }

\end{DoxyCode}
\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22321}{}\doxysubsubsection{$<$a name=\char`\"{}impl\char`\"{}$>$$<$/a$>$ $<$tt$>$proto.\+impl($<$target$>$, $<$types$>$?, $<$implementations$>$?)$<$/tt$>$}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22321}
Adds a new implementation to the given protocol across {\ttfamily $<$types$>$}.

{\ttfamily $<$implementations$>$} must be an object with functions matching the protocol\textquotesingle{}s API. If given, the types in {\ttfamily $<$types$>$} will be mapped to their corresponding method arguments according to the original protocol definition.

If a protocol is derivable -- that is, all its functions have default impls, then the {\ttfamily $<$implementations$>$} object can be omitted entirely, and the protocol will be automatically derived for the given {\ttfamily $<$types$>$}\hypertarget{md_sfcode_node_modules_protoduck_README_autotoc_md22322}{}\doxyparagraph{Example}\label{md_sfcode_node_modules_protoduck_README_autotoc_md22322}

\begin{DoxyCode}{0}
\DoxyCodeLine{import protoduck from 'protoduck'}
\DoxyCodeLine{}
\DoxyCodeLine{// Singly-\/dispatched protocols}
\DoxyCodeLine{const Show = protoduck.define(\{}
\DoxyCodeLine{  show: []}
\DoxyCodeLine{\})}
\DoxyCodeLine{}
\DoxyCodeLine{class Foo \{}
\DoxyCodeLine{  constructor (name) \{}
\DoxyCodeLine{    this.name = name}
\DoxyCodeLine{  \}}
\DoxyCodeLine{\}}
\DoxyCodeLine{}
\DoxyCodeLine{Show.impl(Foo, \{}
\DoxyCodeLine{  show () \{ return `[object Foo(\$\{this.name\})]` \}}
\DoxyCodeLine{\})}
\DoxyCodeLine{}
\DoxyCodeLine{const f = new Foo('alex')}
\DoxyCodeLine{f.show() === '[object Foo(alex)]' }

\end{DoxyCode}



\begin{DoxyCode}{0}
\DoxyCodeLine{import protoduck from 'protoduck'}
\DoxyCodeLine{}
\DoxyCodeLine{// Multi-\/dispatched protocols}
\DoxyCodeLine{const Comparable = protoduck.define(['target'], \{}
\DoxyCodeLine{  compare: ['target'],}
\DoxyCodeLine{\})}
\DoxyCodeLine{}
\DoxyCodeLine{class Foo \{\}}
\DoxyCodeLine{class Bar \{\}}
\DoxyCodeLine{class Baz \{\}}
\DoxyCodeLine{}
\DoxyCodeLine{Comparable.impl(Foo, [Bar], \{}
\DoxyCodeLine{  compare (bar) \{ return 'bars are ok' \}}
\DoxyCodeLine{\})}
\DoxyCodeLine{}
\DoxyCodeLine{Comparable.impl(Foo, [Baz], \{}
\DoxyCodeLine{  compare (baz) \{ return 'but bazzes are better' \}}
\DoxyCodeLine{\})}
\DoxyCodeLine{}
\DoxyCodeLine{const foo = new Foo()}
\DoxyCodeLine{const bar = new Bar()}
\DoxyCodeLine{const baz = new Baz()}
\DoxyCodeLine{}
\DoxyCodeLine{foo.compare(bar) // 'bars are ok'}
\DoxyCodeLine{foo.compare(baz) // 'but bazzes are better' }

\end{DoxyCode}
 