adds some comments

packages/ts-etl/src/cli.ts

@@ -4,18 +4,23 @@ import { isLeft } from 'fp-ts/lib/Either'
 import { ItemOpts, ItemCmd } from './commands'
 import { Client } from './plugins/crossref'
 
+export type PLUGIN_TYPE = 'crossref-api'
+
+const stdoutWrite = (str: string) => process.stdout.write(str)
+
 /**
- * CLI - the default export
+ * CLI
+ *
+ * the MakeCli function creates instances of the Cli,
+ * which is useful for re-use in test. The executable
+ * script for this tool will use the singleton cli
+ * (the default export).
  *
- * invoke this as a library by calling `parseAsync`--
- *   with no args, as in index.ts, it uses argv.
+ * Invoke this as a library by calling `MakeCli().parseAsync`.
+ *   with no args, as in index.ts, parseAsync uses argv.
  *   or pass in string array to parse flags.
  */
 
-export type PLUGIN_TYPE = 'crossref-api'
-
-const stdoutWrite = (str: string) => process.stdout.write(str)
-
 export function MakeCli() {
   const cli = new Command()
 

packages/ts-etl/src/commands.ts

@@ -10,36 +10,43 @@ import type { ErrorOrDocmap } from './types'
 // .. although actually, the streaming may be a layer down instead
 export type Cmd<ArgT extends string[], OptT> = (args: ArgT, opts: OptT) => Promise<ErrorOrDocmap>
 
-// helpcmd is the one type that does not need defining
-// export const HelpCmd: Cmd<{}> = (s, opts) => {
-//   console.log(s =
-// };
-
-// export interface StreamOpts {
-//   source: 'crossref-api'
-// }
-
 export interface CrossrefConfiguration {
   preset: 'crossref-api'
   client: CrossrefClient
 }
 
+/**
+ * ItemOpts
+ *
+ * Configuration for a single Item invocation.
+ */
 export interface ItemOpts {
   source: CrossrefConfiguration
   publisher: DocmapPublisherT
 }
 
+/**
+ * ItemCmd
+ *
+ * Generates a Docmap for a single DOI. Behavior
+ * may depend on the source configuration provided.
+ */
+export const ItemCmd: Cmd<[string], ItemOpts> = ([doi], opts) => {
+  return crossref.fetchPublicationByDoi(opts.source.client, opts.publisher, doi)
+}
+
+/**
+ * PageCmd
+ *
+ * Needs implementation!
+ */
 export interface PageOpts {
   source: CrossrefConfiguration
   prefix: string
   rowsPerPage?: number
   pageNumber?: number
 }
 
-export const ItemCmd: Cmd<[string], ItemOpts> = ([doi], opts) => {
-  return crossref.fetchPublicationByDoi(opts.source.client, opts.publisher, doi)
-}
-
 export const PageCmd: Cmd<[], PageOpts> = async (_a, _opts) => {
   return right([])
 }