Updated SomeId to allow null (#35)

Updated `SomeId` to allow `null` as a valid `_id` because, well, it's technically allowed since it's a JSON scalar.

Author: toptobes

etc/astra-db-ts.api.md

@@ -962,7 +962,7 @@ export interface RunCommandOptions extends WithNamespace, WithTimeout {
 export type SomeDoc = Record<string, any>;
 
 // @public
-export type SomeId = string | number | bigint | boolean | Date | UUID | ObjectId;
+export type SomeId = string | number | bigint | boolean | Date | UUID | ObjectId | null;
 
 // @public
 export type Sort = Record<string, SortDirection> | {

src/data-api/ids.ts

@@ -12,9 +12,21 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { uuidv4, uuidv7, UUID as UUIDv7 } from 'uuidv7';
+import { UUID as UUIDv7, uuidv4, uuidv7 } from 'uuidv7';
 import MongoObjectId from 'bson-objectid';
 
+/**
+ * All possible types for a document ID. JSON scalar types, `Date`, `UUID`, and `ObjectId`.
+ *
+ * Note that the `_id` *can* technically be `null`. Trying to set the `_id` to `null` doesn't mean "auto-generate
+ * an ID" like it may in some other databases; it quite literally means "set the ID to `null`".
+ *
+ * It's heavily recommended to properly type this in your Schema, so you know what to expect for your `_id` field.
+ *
+ * @public
+ */
+export type SomeId = string | number | bigint | boolean | Date | UUID | ObjectId | null;
+
 const uuidRegex = new RegExp('^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$');
 
 /**

src/data-api/types/common.ts

@@ -12,16 +12,9 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import { ObjectId, SomeDoc, UUID, WithId } from '@/src/data-api';
+import { SomeDoc, WithId } from '@/src/data-api';
 import type { ToDotNotation } from '@/src/data-api/types';
 
-/**
- * All possible types for a document ID. JSON scalar types, `Date`, `UUID`, and `ObjectId`.
- *
- * @public
- */
-export type SomeId = string | number | bigint | boolean | Date | UUID | ObjectId;
-
 /**
  * Allowed types to specify an ascending or descending sort.
  *

src/data-api/types/utils.ts

@@ -12,7 +12,8 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-import type { SomeId } from '@/src/data-api/types';
+
+import { SomeId } from '@/src/data-api';
 
 /**
  * Checks if a type can possibly be some number

tests/integration/data-api/collection/insert-one.test.ts

@@ -37,18 +37,26 @@ describe('integration.data-api.collection.insert-one', () => {
     assert.ok(res.insertedId, '123');
   });
 
+  it('should insertOne document with a null id', async () => {
+    const res = await collection.insertOne({ name: 'Lzzy', _id: null });
+    assert.ok(res);
+    assert.strictEqual(res.insertedId, null);
+    const found = await collection.findOne({ _id: null });
+    assert.strictEqual(found?.name, 'Lzzy');
+  });
+
   it('should insertOne document with a UUID', async () => {
     const id = UUID.v7();
     const res = await collection.insertOne({ _id: id });
     assert.ok(res);
-    assert.strictEqual(res.insertedId.toString(), id.toString());
+    assert.strictEqual(res.insertedId?.toString(), id.toString());
   });
 
   it('should insertOne document with an ObjectId', async () => {
     const id = new ObjectId();
     const res = await collection.insertOne({ _id: id });
     assert.ok(res);
-    assert.strictEqual(res.insertedId.toString(), id.toString());
+    assert.strictEqual(res.insertedId?.toString(), id.toString());
   });
 
   it('should insertOne document with a non-_id UUID', async () => {

tests/typing/strict-filter.ts

@@ -14,8 +14,8 @@
 
 /* eslint-disable @typescript-eslint/no-unused-vars */
 
-import type { SomeDoc } from '@/src/data-api';
-import type { SomeId, StrictFilter } from '@/src/data-api/types';
+import type { SomeDoc, SomeId } from '@/src/data-api';
+import type { StrictFilter } from '@/src/data-api/types';
 import type { ConvolutedSchema2, Equal, Expect, Schema, SuperBasicSchema } from '@/tests/typing/prelude';
 
 type test1 = Expect<Equal<StrictFilter<SuperBasicSchema>, {