feat(core): make it easier to create a cotar from tar and tar index (#542)

#### Description

It is sometimes very useful to have two seperate files for a cotar,
`.tar` and `.tar.index` but its somewhat hard to make the cotar from the
two seperate files



#### Intention

Add a builder `Cotar.fromTarIndex(tar, index)` to make it easier to
create them.

#### Checklist
*If not applicable, provide explanation of why.*
- [ ] Tests updated
- [ ] Docs updated
- [ ] Issue linked in Title

Author: blacha

packages/core/README.md

@@ -10,13 +10,28 @@ To fetch a single tile, the index has to be loaded into memory then the cotar ob
 
 ```typescript
 import { Cotar } from '@cotar/core';
-import { SourceUrl } from '@chunkd/source-url';
+import { SourceHttp } from '@chunkd/source-http';
 
-const source = new SourceUrl('s3://linz-basemaps/topographic.tar.co');
-const cotar = Cotar.fromTar(source);
+const source = new SourceHttp('s3://linz-basemaps/topographic.tar.co');
+const cotar = await Cotar.fromTar(source);
 
-// Fetch a gzipped PBF file from  a tar
-const bytes = await cotar.get(`tiles/z10/5/5.pbf.gz`);
+// Fetch a gzipped PBF file from a tar
+const bytes = await cotar.get(`tiles/10/5/5.pbf.gz`);
+```
+
+Index files can also be stored as separate files
+
+```typescript
+import { Cotar } from '@cotar/core';
+import { SourceHttp } from '@chunkd/source-http';
+
+const source = new SourceHttp('s3://linz-basemaps/topographic.tar');
+const sourceIndex = new SourceHttp('s3://linz-basemaps/topographic.tar.index');
+
+const cotar = await Cotar.fromTarIndex(source, index);
+
+// Fetch a gzipped PBF file from a tar
+const bytes = await cotar.get(`tiles/10/5/5.pbf.gz`);
 ```
 
 ### Creating indexes

packages/core/src/cotar.ts

@@ -21,6 +21,27 @@ export class Cotar {
     this.index = index;
   }
 
+  /**
+   * Create a cotar using two sources, one for the tar, one for the index
+   *
+   * @param source the tar asset file generally a file ending with ".tar"
+   * @param index the tar index generally a file ending with ".tar.index"
+   *
+   * @returns a Cotar instance
+   *
+   */
+  static async fromTarIndex(source: Source, index: Source): Promise<Cotar> {
+    const metadata = await CotarIndex.create(index);
+    return new Cotar(source, metadata);
+  }
+
+  /**
+   * Create a cotar from a single archive, generally a ".tar.co"
+   *
+   * @param source asset containing both the tar and the tar index.
+   *
+   * @returns a Cotar instance
+   */
   static async fromTar(source: Source): Promise<Cotar> {
     // Load the last file in the tar archive
     const metadata = await CotarIndex.getMetadata(source, 0, false);