Upddated some typings + updated readme

Author: toptobes

README.md

@@ -2,15 +2,13 @@
 
 `astra-db-ts` is a TypeScript client for interacting with [DataStax Astra DB](https://astra.datastax.com/signup).
 
-*This README targets v1.0.0+, which introduces a whole new API. Click [here](https://www.youtube.com/watch?v=dQw4w9WgXcQ) for the pre-existing client readme.*
-
-*For the sake of my job, I hope I remember to update that link before release.*
+*This README targets v1.0.0+, which introduces a whole new API. Click [here](https://github.com/datastax/astra-db-ts/tree/90ebeac6fec53fd951126c2bcc010c87f7f678f8?tab=readme-ov-file#datastaxastra-db-ts) for the pre-existing client readme.*
 
 ## Quickstart
 
-Use your preferred package manager to install `@datastax/astra-db-ts`. Note that this requires a Node-compatable runtime.
+Use your preferred package manager to install `@datastax/astra-db-ts`. Note that this is not supported in browsers.
 
-Get the *API endpoint* and your *applicaton token* for your Astra DB instance @ [astra.datastax.com](https://astra.datastax.com).
+Get the *API endpoint* and your *application token* for your Astra DB instance @ [astra.datastax.com](https://astra.datastax.com).
 
 Try the following code after setting the following environment variables:
 
@@ -93,7 +91,7 @@ Next steps:
 
 ### Abstraction diagram
 
-astra-db-ts's abstractions for working at the data and admin layers are structured as depicted by this diagram:
+`astra-db-ts`'s abstractions for working at the data and admin layers are structured as depicted by this diagram:
 
 ![Class hierarchy diagram](assets/imgs/class-hierarchy.png)
 
@@ -118,17 +116,106 @@ const admin = client.admin();
 })();
 ```
 
-## Working with ObjectIds and UUIDs
+### Getting the most out of the typing
+
+`astra-db-ts` is a typescript-first library, performing minimal runtime type-checking. As such, it provides
+a rich set of types to help you write type-safe code.
+
+Here are some examples of how you can properly leverage types to make your code more robust:
+
+```typescript
+import { DataAPIClient, StrictFilter, StrictSort, UUID } from '@/src/index';
+
+const client = new DataAPIClient('*TOKEN*');
+const db = client.db('*ENDPOINT*', { namespace: '*NAMESPACE*' });
+
+// You can strictly type your collections for proper type-checking
+interface Person {
+  _id: UUID,
+  name: string,
+  interests: {
+    favoriteBand?: string,
+    friend?: UUID,
+  }
+}
+
+(async () => {
+  // Create your collections with a defaultId type to enforce the type of the _id field
+  // (Otherwise it'll default to a string UUID that wouldn't be deserialized as a UUID by the client)
+  const collection = await db.createCollection<Person>('my_collection', { defaultId: { type: 'uuidv7' } });
+
+  // Now it'll raise type-errors if you try to insert a document with the wrong shape
+  await collection.insertOne({
+    _id: new UUID('e7f1f3a0-7e3d-11eb-9439-0242ac130002'),
+    name: 'John',
+    interests: {
+      favoriteBand: 'Nightwish',
+    },
+    // @ts-expect-error - 'eyeColor' does not exist in type MaybeId<Person>
+    eyeColor: 'blue',
+  });
+
+  // You can use the 'Strict*' version of Sort/Projection/Filter/UpdateFilter for proper type-checking and autocomplete
+  await collection.findOne({
+    // @ts-expect-error - Type number is not assignable to type FilterExpr<UUID | undefined>
+    'interests.friend': 3,
+  } satisfies StrictFilter<Person>, {
+    sort: {
+      name: 1,
+      // @ts-expect-error - 'interests.favoriteColor' does not exist in type StrictProjection<Person>
+      'interests.favoriteColor': 1 as const,
+    } satisfies StrictSort<Person>,
+  });
+})();
+```
+
+### Working with Dates
+
+Native JS `Date` objects can be used anywhere in documents to represent dates and times.
+
+Document fields stored using the `{ $date: number }` will also be returned as Date objects when read.
+
+```typescript
+import { DataApiClient } from '@datastax/astra-db-ts';
+
+// Reference an untyped collection
+const client = new DataApiClient('TOKEN');
+const db = client.db('ENDPOINT', { namespace: 'NAMESPACE' });
+const collection = db.collection('COLLECTION');
+
+// Insert documents with some dates
+await collection.insertOne({ dateOfBirth: new Date(1394104654000) });
+await collection.insertOne({ dateOfBirth: new Date('1863-05-28') });
+
+// Update a document with a date and setting lastModified to now
+await collection.updateOne(
+  {
+    dateOfBirth: new Date('1863-05-28'),
+  },
+  {
+    $set: { message: 'Happy Birthday!' },
+    $currentDate: { lastModified: true },
+  },
+);
+
+// Will print *around* `new Date()` (i.e. when server processed the request)
+const found = await collection.findOne({ dateOfBirth: { $lt: new Date('1900-01-01') } });
+console.log(found?.lastModified);
+```
+
+### Working with ObjectIds and UUIDs
+
+`astra-db-ts` exports an `ObjectId` and `UUID` class for working with these types in the database.
 
-astra-db-ts exports an `ObjectId` and `UUID` class for working with these types in the database. Here's an example:
+Note that these are custom classes, and *not* the ones from the `bson` package. Make sure you're using the right one!
 
 ```typescript
 import { DataAPIClient, ObjectId, UUID } from '@datastax/astra-db-ts';
 
 interface Person {
   _id: ObjectId | UUID,
   name: string,
-  friendId?: string,
+  friendId?: ObjectId | UUID,
 }
 
 // Connect to the db
@@ -152,7 +239,7 @@ const db = client.db('*ENDPOINT*', { namespace: '*NAMESPACE*' });
 
   await collection.updateOne(
     { name: 'Jane' },
-    { $set: { friendId: friendId.toString() } },
+    { $set: { friendId } },
   );
 
   // And let's get Jane as a document
@@ -162,4 +249,44 @@ const db = client.db('*ENDPOINT*', { namespace: '*NAMESPACE*' });
 })();
 ```
 
-Note that these are custom classes, and *not* the ones from the `bson` package. Make sure you're using the right one!
+### Monitoring/logging
+
+[Like Mongo](https://www.mongodb.com/docs/drivers/node/current/fundamentals/logging/), `astra-db-ts` doesn't provide a
+traditional logging system—instead, it uses a "monitoring" system based on event emitters, which allow you to listen to
+events and log them as you see fit.
+
+Supported events include `commandStarted`, `commandSucceeded`, `commandFailed`, and `adminCommandStarted`,
+`adminCommandPolling`, `adminCommandSucceeded`, `adminCommandFailed`.
+
+Note that it's disabled by default, and it can be enabled by passing `monitorCommands: true` option to the root options'
+`dbOptions` and `adminOptions`.
+
+```typescript
+import { DataAPIClient } from '@datastax/astra-db-ts';
+
+const client = new DataAPIClient('*TOKEN*', {
+  dbOptions: {
+    monitorCommands: true,
+  },
+});
+
+client.on('commandStarted', (event) => {
+  console.log(`Running command ${event.commandName}`);
+});
+
+client.on('commandSucceeded', (event) => {
+  console.log(`Command ${event.commandName} succeeded in ${event.duration}ms`);
+});
+
+client.on('commandFailed', (event) => {
+  console.error(`Command ${event.commandName} failed w/ error ${event.error}`);
+});
+
+const db = client.db('*ENDPOINT*');
+const coll = db.collection('*COLLECTION*');
+
+// Should log
+// - "Running command insertOne"
+// - "Command insertOne succeeded in <time>ms"
+await coll.insertOne({ name: 'Queen' });
+```

src/data-api/collection.ts

@@ -930,7 +930,7 @@ export class Collection<Schema extends SomeDoc = SomeDoc> {
    *
    * @see StrictFilter
    */
-  public async findOne<GetSim extends boolean = false>(filter: Filter<Schema>, options?: FindOneOptions<GetSim>): Promise<FoundDoc<Schema, GetSim> | null> {
+  public async findOne<const GetSim extends boolean = false>(filter: Filter<Schema>, options?: FindOneOptions<GetSim>): Promise<FoundDoc<Schema, GetSim> | null> {
     options = coalesceVectorSpecialsIntoSort(options);
 
     const command: FindOneCommand = {

src/data-api/types/dot-notation.ts

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import type { SomeDoc } from '@/src/data-api';
+import { SomeDoc, UUID, ObjectId } from '@/src/data-api';
 
 /**
  * Converts some {@link Schema} into a type representing its dot notation (object paths).
@@ -45,9 +45,9 @@ import type { SomeDoc } from '@/src/data-api';
  * }
  * ```
  */
-export type ToDotNotation<Schema extends SomeDoc> = Merge<_ToDotNotation<Required<Schema>, ''>>;
+export type ToDotNotation<Schema extends SomeDoc> = Merge<_ToDotNotation<Schema, ''>>;
 
-type _ToDotNotation<Elem extends SomeDoc, Prefix extends string> = {
+type _ToDotNotation<_Elem extends SomeDoc, Prefix extends string, Elem = Required<_Elem>> = {
   [Key in keyof Elem]:
     SomeDoc extends Elem
       ? (
@@ -64,6 +64,8 @@ type _ToDotNotation<Elem extends SomeDoc, Prefix extends string> = {
         | { [Path in `${Prefix}${Key & string}`]: Elem[Key] }
         | { [Path in `${Prefix}${Key & string}.${number}`]: Elem[Key][number] }
         ) :
+    Elem[Key] extends UUID | ObjectId
+      ? { [Path in `${Prefix}${Key & string}`]: Elem[Key] } :
     Elem[Key] extends Date
       ? { [Path in `${Prefix}${Key & string}`]: Date | { $date: number } } :
     Elem[Key] extends SomeDoc

tests/typing/dot-notation.ts

@@ -14,9 +14,9 @@
 
 /* eslint-disable @typescript-eslint/no-unused-vars */
 
-import { BasicSchema, ConvolutedSchema1, Equal, Expect, Schema } from '@/tests/typing/prelude';
+import { BasicSchema, ConvolutedSchema1, ConvolutedSchema3, Equal, Expect, Schema } from '@/tests/typing/prelude';
 import { ToDotNotation } from '@/src/data-api/types';
-import { SomeDoc } from '@/src/data-api';
+import { SomeDoc, UUID } from '@/src/data-api';
 
 type test1 = Expect<Equal<ToDotNotation<BasicSchema>, {
   num: number,
@@ -35,7 +35,7 @@ type test2 = Expect<Equal<ToDotNotation<Schema>, {
   'obj.str2': string,
   'obj.obj': { num: number, any: SomeDoc },
   'obj.obj.num': number,
-  'obj.obj.any': SomeDoc,
+  'obj.obj.any': SomeDoc & Required<SomeDoc>,
   [k: `obj.obj.any.${string}`]: any,
   arr: string[],
   [k: `arr.${number}`]: string,
@@ -104,3 +104,7 @@ const test9: Partial<ToDotNotation<ConvolutedSchema1>> = {
   // @ts-expect-error - Invalid type
   numOrString: 1n,
 }
+
+const test10: Partial<ToDotNotation<ConvolutedSchema3>> = {
+  'obj.id': UUID.v7(),
+}

tests/typing/prelude.ts

@@ -12,7 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { SomeDoc } from '@/src/data-api';
+import { SomeDoc, UUID } from '@/src/data-api';
+import { ObjectId } from 'bson';
 
 export type Equal<X, Y> = (<T>() => T extends X ? 1 : 2) extends (<T>() => T extends Y ? 1 : 2) ? true : false;
 export type Expect<T extends true> = T;
@@ -55,3 +56,9 @@ export interface ConvolutedSchema1 {
 export interface ConvolutedSchema2 {
   numOrArray: number | string[],
 }
+
+export interface ConvolutedSchema3 {
+  obj: {
+    id: UUID | ObjectId,
+  }
+}