Minor ts-doc cleanup (#30)

* updated some ts-doc in db.ts

* added quick explanation as to why close() exists

* Improved sort/projection documentation

* couple minor doc updates

* commented the build script

Author: toptobes

scripts/build.sh

@@ -1,12 +1,25 @@
 #!/usr/bin/sh
 
+# Cleans the previous build
 rm -rf ./dist
+
+# Creates the version file
 echo "export const LIB_NAME = 'astra-db-ts';" > src/version.ts
 node -p "'export const LIB_VERSION = ' + JSON.stringify(require('./package.json').version) + ';'" >> src/version.ts
+
+# Transpiles the project
 npx tsc --project tsconfig.build.json
+
+# Replaces alias paths with relative paths (e.g. `@/src/version` -> `../../src/version`)
 npx tsc-alias -p tsconfig.build.json
+
+# Creates the rollup .d.ts and generates an API report in etc/
 npm run api-extractor
+
+# Deletes the temp folder that was created by API extractor
 rm -r ./temp
+
+# Removes all .d.ts files except the main rollup .d.ts
 cd dist || return 1
 find . -type f -name '*.d.ts' ! -name 'astra-db-ts.d.ts' -exec rm {} +
 cd ..

src/client/data-api-client.ts

@@ -49,8 +49,9 @@ export type DataAPIClientEvents =
   & AdminCommandEvents
 
 /**
- * The base class for the {@link DataAPIClient} event emitter to make it properly typed. Should probably never need
- * to be used directly.
+ * The base class for the {@link DataAPIClient} event emitter to make it properly typed.
+ *
+ * Should probably never need to be used directly.
  *
  * @public
  */
@@ -247,6 +248,17 @@ export class DataAPIClient extends DataAPIClientEventEmitterBase {
    * @remarks
    * This method is idempotent and can be called multiple times without issue.
    *
+   * --
+   *
+   * For most users, this method isn't necessary to call, as resources will be freed up when the
+   * server is shut down or the process is killed. However, it's useful in long-running processes or when you want to
+   * free up resources immediately.
+   *
+   * --
+   *
+   * Think of it as using malloc or using a file descriptor. Freeing them isn't always strictly necessary for
+   * long-running usages, but it's there for when you need it.
+   *
    * @returns A promise that resolves when the client has been closed.
    */
   public async close(): Promise<void> {

src/data-api/cursor.ts

@@ -315,10 +315,6 @@ export class FindCursor<T, TRaw extends SomeDoc = SomeDoc> {
    * resultant data was already fetched by this cursor.
    */
   rewind(): void {
-    // if (this._state === CursorStatus.Uninitialized) {
-    //   return;
-    // }
-
     this._buffer.length = 0;
     this._nextPageState = undefined;
     this._state = CursorStatus.Uninitialized;

src/data-api/db.ts

@@ -52,7 +52,7 @@ import { InternalRootClientOpts } from '@/src/client/types';
  *
  * // Overrides default options from the DataAPIClient
  * const db2 = client.db('https://<db_id>-<region>.apps.astra.datastax.com', {
- *   namespace: 'my-namespace',
+ *   namespace: 'my_namespace',
  *   useHttp2: false,
  * });
  *
@@ -78,18 +78,18 @@ export class Db {
    * ```typescript
    *
    * // Uses 'default_keyspace' as the default namespace for all future db spawns
-   * const client1 = new DataAPIClient('AstraCS:...');
+   * const client1 = new DataAPIClient('*TOKEN*');
    *
    * // Overrides the default namespace for all future db spawns
-   * const client2 = new DataAPIClient('AstraCS:...', {
+   * const client2 = new DataAPIClient('*TOKEN*', {
    *   dbOptions: { namespace: 'my_namespace' }
    * });
    *
    * // Created with 'default_keyspace' as the default namespace
-   * const db1 = client1.db('https://<db_id>-<region>.apps.astra.datastax.com');
+   * const db1 = client1.db('*ENDPOINT*');
    *
    * // Created with 'my_namespace' as the default namespace
-   * const db2 = client1.db('https://<db_id>-<region>.apps.astra.datastax.com', {
+   * const db2 = client1.db('*ENDPOINT*', {
    *   namespace: 'my_namespace'
    * });
    *
@@ -139,7 +139,7 @@ export class Db {
   }
 
   /**
-   * The ID of the database, if it's an Astra database. If it's a non-Astra database, this will throw an error.
+   * The ID of the database, if it's an Astra database. If it's not an Astra database, this will throw an error.
    *
    * @throws Error - if the database is not an Astra database.
    */
@@ -154,7 +154,7 @@ export class Db {
    * Spawns a new {@link AstraDbAdmin} instance for this database, used for performing administrative operations
    * on the database, such as managing namespaces, or getting database information.
    *
-   * **NB. This method will throw an error if the database is not an Astra database.**
+   * **NB. Only available for Astra databases.**
    *
    * The given options will override any default options set when creating the {@link DataAPIClient} through
    * a deep merge (i.e. unset properties in the options object will just default to the default options).
@@ -184,13 +184,13 @@ export class Db {
   /**
    * Fetches information about the database, such as the database name, region, and other metadata.
    *
+   * **NB. Only available for Astra databases.**
+   *
    * For the full, complete, information, see {@link AstraDbAdmin.info}.
    *
    * The method issues a request to the DevOps API each time it is invoked, without caching mechanisms;
    * this ensures up-to-date information for usages such as real-time collection validation by the application.
    *
-   * Only available for Astra databases.
-   *
    * @example
    * ```typescript
    * const info = await db.info();
@@ -249,9 +249,9 @@ export class Db {
   }
 
   /**
-   * Fetches all the collections in the database (& in the working/given namespace), and establishes references to them.
+   * Establishes references to all the collections in the working/given namespace.
    *
-   * You can also specify a namespace in the options parameter, which will override the default namespace for this database.
+   * You can specify a namespace in the options parameter, which will override the default namespace for this `Db` instance.
    *
    * @example
    * ```typescript
@@ -269,11 +269,9 @@ export class Db {
    * @returns A promise that resolves to an array of references to the working Db's collections.
    */
   public async collections(options?: WithNamespace & WithTimeout): Promise<Collection[]> {
-    const timeoutManager = this._httpClient.timeoutManager(options?.maxTimeMS);
-
     const collections = await this.listCollections({
       namespace: options?.namespace,
-      maxTimeMS: timeoutManager.msRemaining,
+      maxTimeMS: options?.maxTimeMS,
       nameOnly: true,
     });
 
@@ -283,13 +281,13 @@ export class Db {
   /**
    * Creates a new collection in the database, and establishes a reference to it.
    *
-   * **NB. You are limited to 10 collections per database in Astra, so be wary when using this command.**
+   * **NB. You are limited in the amount of collections you can create, so be wary when using this command.**
    *
    * This is a blocking command which performs actual I/O unlike {@link Db.collection}, which simply creates an
    * unvalidated reference to a collection.
    *
-   * **If `checkExists: false`, creation is idempotent, so if the collection already exists with the same options,
-   * this method will not throw an error. If the options differ though, it'll raise an error.**
+   * If `checkExists: false`, creation is idempotent, so if the collection already exists with the same options,
+   * this method will not throw an error. If the options mismatch, it will throw a {@link DataAPIResponseError}.
    *
    * Typed as `Collection<SomeDoc>` by default, but you can specify a schema type to get a typed collection. If left
    * as `SomeDoc`, the collection will be untyped.
@@ -298,6 +296,8 @@ export class Db {
    *
    * You can also specify a namespace in the options parameter, which will override the default namespace for this database.
    *
+   * See {@link CreateCollectionOptions} for *much* more information on the options available.
+   *
    * @example
    * ```typescript
    * interface User {
@@ -314,6 +314,7 @@ export class Db {
    *   defaultId: {
    *     type: "objectId",
    *   },
+   *   checkExists: false,
    * });
    * ```
    *
@@ -322,6 +323,8 @@ export class Db {
    *
    * @returns A promised reference to the newly created collection.
    *
+   * @throws CollectionAlreadyExistsError - if the collection already exists and `checkExists` is `true` or unset.
+   *
    * @see SomeDoc
    * @see VectorDoc
    */
@@ -433,6 +436,7 @@ export class Db {
     const command: ListCollectionsCommand = {
       findCollections: {
         options: {
+          // Is 'nameOnly' instead of 'explain' for Mongo-compatibility reasons
           explain: options?.nameOnly !== true,
         },
       },

src/data-api/types/collections/collections-common.ts

@@ -92,8 +92,8 @@ export interface VectorizeServiceOptions {
  * @public
  */
 export type IndexingOptions<Schema extends SomeDoc> =
-  | { allow: (keyof ToDotNotation<Schema>)[] | ['*'], deny?: never }
-  | { deny: (keyof ToDotNotation<Schema>)[] | ['*'], allow?: never }
+  | { allow: (keyof ToDotNotation<Schema>)[] | ['*'], deny?:  never }
+  | { deny:  (keyof ToDotNotation<Schema>)[] | ['*'], allow?: never }
 
 /**
  * Represents the options for the default ID.

src/data-api/types/collections/create-collection.ts

@@ -40,9 +40,14 @@ export interface CreateCollectionCommand {
  */
 export interface CreateCollectionOptions<Schema extends SomeDoc> extends WithTimeout, CollectionOptions<Schema>, WithNamespace {
   /**
-   * If `true`, runs an additional existence check before creating the collection, failing if the collection with the
-   * same name already exists, raising an error. Otherwise, the creation is always attempted, and the command's will
-   * succeed even if the collection with the given name already exists, as long as the options are the exact same.
+   * If `true` or unset, runs an additional existence check before creating the collection, failing if the collection
+   * with the same name already exists, raising a {@link CollectionAlreadyExistsError}.
+   *
+   * Otherwise, if `false`, the creation is always attempted, and the command will succeed even if the collection
+   * with the given name already exists, as long as the options are the exact same (if options mismatch, it'll
+   * throw a {@link DataAPIResponseError}).
+   *
+   * @defaultValue true
    */
   checkExists?: boolean;
 }

src/data-api/types/common.ts

@@ -36,6 +36,8 @@ export type SortDirection = 1 | -1 | 'asc' | 'desc' | 'ascending' | 'descending'
  *
  * Can use `1`/`-1` for ascending/descending, or `$vector` for sorting by vector distance.
  *
+ * See {@link SortDirection} for all possible sort values.
+ *
  * **NB. The order of the fields in the sort option is significant—fields are sorted in the order they are listed.**
  *
  * @example
@@ -52,6 +54,9 @@ export type SortDirection = 1 | -1 | 'asc' | 'desc' | 'ascending' | 'descending'
  * }
  * ```
  *
+ * @see StrictSort
+ * @see SortDirection
+ *
  * @public
  */
 export type Sort =
@@ -64,7 +69,9 @@ export type Sort =
  *
  * **If you want stricter type-checking and full auto-complete, see {@link StrictProjection}.**
  *
- * Can use `1`/`0`, or `true`/`false`
+ * Can use `1`/`0`, or `true`/`false`.
+ *
+ * There's a special field `'*'` that can be used to include/exclude all fields.
  *
  * @example
  * ```typescript
@@ -86,6 +93,8 @@ export type Sort =
  * }
  * ```
  *
+ * @see StrictProjection
+ *
  * @public
  */
 export type Projection = Record<string, 1 | 0 | true | false | ProjectionSlice>;
@@ -95,6 +104,8 @@ export type Projection = Record<string, 1 | 0 | true | false | ProjectionSlice>;
  *
  * Can use `1`/`-1` for ascending/descending, or `$vector` for sorting by vector distance.
  *
+ * See {@link SortDirection} for all possible sort values.
+ *
  * **NB. The order of the fields in the sort option is significant—fields are sorted in the order they are listed.**
  *
  * @example
@@ -115,6 +126,9 @@ export type Projection = Record<string, 1 | 0 | true | false | ProjectionSlice>;
  * });
  * ```
  *
+ * @see Sort
+ * @see SortDirection
+ *
  * @public
  */
 export type StrictSort<Schema extends SomeDoc> =
@@ -125,7 +139,9 @@ export type StrictSort<Schema extends SomeDoc> =
 /**
  * Specifies which fields should be included/excluded in the returned documents.
  *
- * Can use `1`/`0`, or `true`/`false`
+ * Can use `1`/`0`, or `true`/`false`.
+ *
+ * There's a special field `'*'` that can be used to include/exclude all fields.
  *
  * @example
  * ```typescript
@@ -150,6 +166,8 @@ export type StrictSort<Schema extends SomeDoc> =
  * });
  * ```
  *
+ * @see Projection
+ *
  * @public
  */
 export type StrictProjection<Schema extends SomeDoc> = {
@@ -178,6 +196,25 @@ export type StrictProjection<Schema extends SomeDoc> = {
  * { $slice: [-4, 2] }
  * ```
  *
+ * @example
+ * ```typescript
+ * await collection.insertOne({ arr: [1, 2, 3, 4, 5] });
+ *
+ * // Return [1, 2]
+ * await collection.findOne({}, {
+ *   projection: {
+ *     arr: { $slice: 2 },
+ *   },
+ * });
+ *
+ * // Return [3, 4]
+ * await collection.findOne({}, {
+ *   projection: {
+ *     arr: { $slice: [-3, 2] },
+ *   },
+ * });
+ * ```
+ *
  * @public
  */
 export interface ProjectionSlice {

src/data-api/types/filter.ts

@@ -38,6 +38,8 @@ import { IsDate, IsNum } from '@/src/data-api/types/utils';
  * });
  * ```
  *
+ * @see StrictFilter
+ *
  * @public
  */
 export type Filter<Schema extends SomeDoc> = {
@@ -75,6 +77,8 @@ export type Filter<Schema extends SomeDoc> = {
  * } satisfies StrictFilter<BasicSchema>);
  * ```
  *
+ * @see Filter
+ *
  * @public
  */
 export type StrictFilter<Schema extends SomeDoc> = {

src/data-api/types/misc/bulk-write.ts

@@ -133,7 +133,7 @@ export class BulkWriteResult<Schema extends SomeDoc> {
 /**
  * Represents *some* bulk write operation.
  *
- * Be careful not to pass in multiple operations in the same object.
+ * Be careful not to pass in multiple operations in the same object (only one operation per object allowed)
  *
  * @public
  */

src/data-api/types/update-filter.ts

@@ -51,6 +51,8 @@ import { IsDate, IsNum } from '@/src/data-api/types/utils';
  * @field $mul - Multiply the value of a field in the document.
  * @field $addToSet - Add an element to an array field in the document if it does not already exist.
  *
+ * @see StrictUpdateFilter
+ *
  * @public
  */
 export interface UpdateFilter<Schema extends SomeDoc> {
@@ -249,6 +251,8 @@ export interface UpdateFilter<Schema extends SomeDoc> {
  * @field $mul - Multiply the value of a field in the document.
  * @field $addToSet - Add an element to an array field in the document if it does not already exist.
  *
+ * @see UpdateFilter
+ *
  * @public
  */
 export interface StrictUpdateFilter<Schema extends SomeDoc> {