fix(api): improvements based on using in ci build; docs adds (#382)

textileio · Jul 30, 2020 · 805e2cf · 805e2cf
1 parent 85779e4
commit 805e2cf
Show file tree

Hide file tree

Showing 5 changed files with 89 additions and 42 deletions.
diff --git a/etc/hub.api.md b/etc/hub.api.md
@@ -72,7 +72,7 @@ export class Buckets extends BucketsGrpcClient {
     list(): Promise<Root.AsObject[]>;
     listIpfsPath(path: string): Promise<ListPathItem.AsObject | undefined>;
     listPath(key: string, path: string, depth?: number): Promise<ListPathReply.AsObject>;
-    listPathFlat(key: string, path: string, dirs?: boolean, depth?: number): Promise<ListPathFlat>;
+    listPathFlat(key: string, path: string, dirs?: boolean, depth?: number): Promise<Array<string>>;
     // @deprecated
     open(name: string, threadName?: string, isPrivate?: boolean, threadID?: string): Promise<{
         root?: Root.AsObject;
@@ -238,17 +238,11 @@ export { LinksReply }
 
 export { ListIpfsPathReply }
 
-// @public (undocumented)
-export type ListPathFlat = ReturnType<typeof listPathFlat>;
-
 // @public
-export function listPathFlat(grpc: BucketsGrpcClient, bucketKey: string, path: string, dirs: boolean, depth: number): Promise<string[]>;
+export function listPathFlat(grpc: BucketsGrpcClient, bucketKey: string, path: string, dirs: boolean, depth: number): Promise<Array<string>>;
 
 export { ListPathItem }
 
-// @public (undocumented)
-export type ListPathRecursive = ReturnType<typeof listPathRecursive>;
-
 // @public
 export function listPathRecursive(grpc: BucketsGrpcClient, bucketKey: string, path: string, depth: number, currentDepth?: number): Promise<ListPathReply.AsObject>;
 

diff --git a/packages/buckets/src/buckets.spec.ts b/packages/buckets/src/buckets.spec.ts
@@ -145,16 +145,16 @@ describe('Buckets...', () => {
 
     // Recursive dir
     // [
-    //   'mybuck',
-    //   'mybuck/.textileseed',
-    //   'mybuck/dir1',
-    //   'mybuck/dir1/file1.jpg',
-    //   'mybuck/path',
-    //   'mybuck/path/to',
-    //   'mybuck/path/to/file2.jpg'
+    //   '.textileseed',
+    //   'dir1',
+    //   'dir1/file1.jpg',
+    //   'path',
+    //   'path/to',
+    //   'path/to/file2.jpg'
     // ]
     let list = await client.listPathFlat(rootKey, '')
-    expect(list).to.have.length(7)
+    expect(list).to.have.length(6)
+    expect(list).to.contain('dir1/file1.jpg')
 
     list = await client.listPathFlat(rootKey, '', false)
     expect(list).to.have.length(3)

diff --git a/packages/buckets/src/buckets.ts b/packages/buckets/src/buckets.ts
@@ -32,7 +32,7 @@ import {
   bucketsInit,
   PushPathResult,
 } from './api'
-import { listPathRecursive, listPathFlat, ListPathRecursive, ListPathFlat } from './utils'
+import { listPathRecursive, listPathFlat } from './utils'
 
 const logger = log.getLogger('buckets')
 
@@ -45,7 +45,7 @@ const logger = log.getLogger('buckets')
  *
  * const getOrInit = async (auth: UserAuth, bucketName: string) => {
  *   const buckets = Buckets.withUserAuth(auth)
- *   // Automatically scopes future calls to the Thread containing the bucket
+ *   // Automatically scopes future calls on `buckets` to the Thread containing the bucket
  *   const { root, threadID } = await buckets.getOrInit(bucketName)
  *   if (!root) throw new Error('bucket not created')
  *   const bucketKey = root.key
@@ -77,6 +77,31 @@ const logger = log.getLogger('buckets')
  *     return roots.find((bucket) => bucket.name === bucketName)
  * }
  * ```
+ *
+ * @example
+ * Push an folder in node.js
+ * ```typescript
+ * import fs from 'fs'
+ * import util from 'util'
+ * import glob from 'glob'
+ * import { Buckets } from '@textile/hub'
+ *
+ * const globDir = util.promisify(glob)
+ *
+ * // expects an already setup buckets session using getOrInit or withThread
+ * const exists = async (buckets: Buckets, bucketKey: string, dir: string) => {
+ *   const files = await globDir('<dir glob options>')
+ *   return await Promise.all(files.map(async (file) => {
+ *     const filePath = dir + '/' + file
+ *     var content = fs.createReadStream(filePath, { highWaterMark: 1024 * 1024 * 3 });
+ *     const upload = {
+ *       path: file,
+ *       content
+ *     }
+ *     return await buckets.pushPath(bucketKey, file, upload)
+ *   }))
+ * }
+ * ```
  */
 export class Buckets extends BucketsGrpcClient {
   /**
@@ -127,6 +152,7 @@ export class Buckets extends BucketsGrpcClient {
 
   /**
    * Open a new / existing bucket by bucket name and ThreadID (init not required)
+   * Replaces `open` command in older versions.
    * @param name name of bucket
    * @param threadName the name of the thread where the bucket is stored (default `buckets`)
    * @param isPrivate encrypt the bucket contents (default `false`)
@@ -306,17 +332,16 @@ export class Buckets extends BucketsGrpcClient {
    *   console.log(list)
    * }
    * // [
-   * //   'mybuck',
-   * //   'mybuck/.textileseed',
-   * //   'mybuck/dir1',
-   * //   'mybuck/dir1/file1.jpg',
-   * //   'mybuck/path',
-   * //   'mybuck/path/to',
-   * //   'mybuck/path/to/file2.jpg'
+   * //   '.textileseed',
+   * //   'dir1',
+   * //   'dir1/file1.jpg',
+   * //   'path',
+   * //   'path/to',
+   * //   'path/to/file2.jpg'
    * // ]
    * ```
    */
-  async listPathFlat(key: string, path: string, dirs = true, depth = 5): Promise<ListPathFlat> {
+  async listPathFlat(key: string, path: string, dirs = true, depth = 5): Promise<Array<string>> {
     logger.debug('list path recursive request')
     return await listPathFlat(this, key, path, dirs, depth)
   }
@@ -348,6 +373,31 @@ export class Buckets extends BucketsGrpcClient {
    *    return await buckets.pushPath(bucketKey!, 'index.html', file)
    * }
    * ```
+   *
+   * @example
+   * Push an folder in node.js
+   * ```typescript
+   * import fs from 'fs'
+   * import util from 'util'
+   * import glob from 'glob'
+   * import { Buckets } from '@textile/hub'
+   *
+   * const globDir = util.promisify(glob)
+   *
+   * // expects an already setup buckets session using getOrInit or withThread
+   * const exists = async (buckets: Buckets, bucketKey: string, dir: string) => {
+   *   const files = await globDir('<dir glob options>')
+   *   return await Promise.all(files.map(async (file) => {
+   *     const filePath = dir + '/' + file
+   *     var content = fs.createReadStream(filePath, { highWaterMark: 1024 * 1024 * 3 });
+   *     const upload = {
+   *       path: file,
+   *       content
+   *     }
+   *     return await buckets.pushPath(bucketKey, file, upload)
+   *   }))
+   * }
+   * ```
    */
   async pushPath(
     key: string,

diff --git a/packages/buckets/src/utils.ts b/packages/buckets/src/utils.ts
@@ -14,7 +14,6 @@ export function bytesToArray(chunk: Uint8Array, size = 1024 * 1024 * 3) {
   return result
 }
 
-export type ListPathRecursive = ReturnType<typeof listPathRecursive>
 /**
  * listPathRecursive returns a nested object of all paths (and info) in a bucket
  */
@@ -24,10 +23,10 @@ export async function listPathRecursive(
   path: string,
   depth: number,
   currentDepth = 0,
-) {
+): Promise<ListPathReply.AsObject> {
   const rootPath = path === '' || path === '.' || path === '/' ? '' : `${path}/`
   const tree = await bucketsListPath(grpc, bucketKey, path)
-  if (tree.item && (currentDepth + 1 <= depth || depth == -1)) {
+  if (tree.item && (currentDepth + 1 <= depth || depth === -1)) {
     for (let i = 0; i < tree.item.itemsList.length; i++) {
       const obj = tree.item.itemsList[i]
       if (!obj.isdir) continue
@@ -41,33 +40,36 @@ export async function listPathRecursive(
   return tree
 }
 
-async function treeToPaths(tree: ListPathItem.AsObject, path?: string, dirs = true, depth = 5): Promise<Array<string>> {
+async function treeToPaths(
+  tree: ListPathItem.AsObject[],
+  path?: string,
+  dirs = true,
+  depth = 5,
+  currentDepth = 0,
+): Promise<Array<string>> {
   const result = []
-  const fp = path ? `${path}/${tree.name}` : `${tree.name}`
-  // Only push if dirs included or not a dir
-  if (dirs || !tree.isdir) result.push(fp)
-  if (tree.isdir) {
-    for (const item of tree.itemsList) {
-      const downtree = await treeToPaths(item, fp, dirs, depth)
+  for (const item of tree) {
+    const newPath = path === '' ? `${item.name}` : `${path}/${item.name}`
+    if (dirs || !item.isdir) result.push(newPath)
+    if (item.isdir && (currentDepth < depth || depth === -1)) {
+      const downtree = await treeToPaths(item.itemsList, newPath, dirs, depth, currentDepth + 1)
       result.push(...downtree)
     }
   }
   return result
 }
 
-export type ListPathFlat = ReturnType<typeof listPathFlat>
-
 /**
- * utilPathsList returns a string array of all paths in a bucket
+ * listPathFlat returns a string array of all paths in a bucket
  */
 export async function listPathFlat(
   grpc: BucketsGrpcClient,
   bucketKey: string,
   path: string,
   dirs: boolean,
   depth: number,
-) {
+): Promise<Array<string>> {
   const tree = await listPathRecursive(grpc, bucketKey, path, depth)
   if (!tree.item) return []
-  return treeToPaths(tree.item, undefined, dirs)
+  return treeToPaths(tree.item.itemsList, path, dirs)
 }
diff --git a/website/sidebars.json b/website/sidebars.json
@@ -23,14 +23,15 @@
       "hub.buckets.withuserauth",
       "hub.buckets.withkeyinfo",
       "hub.buckets.gettoken",
-      "hub.buckets.getOrInit",
+      "hub.buckets.getorinit",
       "hub.buckets.init",
       "hub.buckets.root",
       "hub.buckets.links",
       "hub.buckets.list",
       "hub.buckets.listpath",
       "hub.buckets.listPathFlat",
       "hub.buckets.listipfspath",
+      "hub.buckets.open",
       "hub.buckets.pushpath",
       "hub.buckets.pullpath",
       "hub.buckets.pullipfspath",