feat(mongodb): Add Object ID keyword converter and update MongoDB CLI & docs (#3041)

Author: marshallswain

docs/.vitepress/config.sidebar.ts

@@ -80,7 +80,7 @@ export default {
     {
       text: 'CLI',
       collapsible: true,
-      collapsed: false,
+      collapsed: true,
       items: [
         {
           text: '📖 Readme',

docs/.vitepress/highlight.ts

@@ -1,6 +1,6 @@
 import { IThemeRegistration, getHighlighter, HtmlRendererOptions } from 'shiki'
 import type { ThemeOptions } from 'vitepress'
-import { getJavaScript, PRETTIERRC } from '@feathersjs/cli/lib/commons'
+import { getJavaScript, PRETTIERRC } from '@feathersjs/generators/lib/commons'
 import prettier from 'prettier'
 
 /**

docs/.vitepress/style/main.postcss

@@ -86,7 +86,6 @@ body .bg-base-100 {
 
 #VPSidebarNav:not(:first-child) {
   @apply mt-3;
-  border-top: 1px solid transparent;
   border-top-color: var(--vp-c-divider-light);
 }
 

docs/api/databases/mongodb.md

@@ -394,101 +394,37 @@ For more information on MongoDB's collation feature, visit the [collation refere
 
 MongoDB uses [ObjectId](https://www.mongodb.com/docs/manual/reference/method/ObjectId/) object as primary keys. To store them in the right format they have to be converted from and to strings.
 
-### AJV format
+### AJV keyword
 
-To validate an ObjectId via the `format` keyword, add the following to your `validators` file:
+To validate and convert strings to an object id using AJV, the `keywordObjectId` [AJV keyword](https://ajv.js.org/api.html#ajv-addkeyword-definition-string-object-ajv) helper can be used. It is set up automatically in a generated application using MongoDB.
 
 ```ts
-// `objectid` formatter
-const formatObjectId = {
-  type: 'string',
-  validate: (id: string | ObjectId) => {
-    if (ObjectId.isValid(id)) {
-      if (String(new ObjectId(id)) === id) return true
-      return false
-    }
-    return false
-  }
-} as const
-
-dataValidator.addFormat('objectid', formatObjectId)
-queryValidator.addFormat('objectid', formatObjectId)
-```
-
-Now you can use it as a `format` option in your schema definitions:
-
-```ts
-// TypeBox
-Type.String({ format: 'objectid' })
-// JSON schema
-const schema = {
-  type: 'string',
-  format: 'objectid'
-}
-```
-
-### Shared Validator
-
-The following utility can be used to create a shared [TypeBox](../schema/typebox.md) type for object ids (e.g. in a `utilities` file):
-
-```ts
-import { Type } from '@feathersjs/typebox'
-
-export const ObjectId = () =>
-  Type.Union([Type.String({ format: 'objectid' }), Type.Object({}, { additionalProperties: true })])
-```
+import { keywordObjectId } from '@feathersjs/mongodb'
 
-Which can then be used like this:
+const validator = new Ajv()
 
-```ts
-import { Type } from '@feathersjs/typebox'
-import { ObjectId } from '../utilities'
-
-const userSchema = Type.Object(
-  {
-    _id: ObjectId(),
-    orgIds: Type.Array(ObjectId())
-  },
-  { $id: 'User', additionalProperties: false }
-)
-```
+validator.addKeyword(keywordObjectId)
 
-### AJV converter
-
-To convert Object Ids, one option is to register an AJV specific converter by adding the following to the the `validators` file:
+const typeboxSchema = Type.Object({
+  userId: Type.String({ objectid: true })
+})
 
-```ts
-// `convert` keyword.
-const keywordConvert = {
-  keyword: 'convert',
-  type: 'string',
-  compile(schemaVal: boolean, parentSchema: AnySchemaObject) {
-    if (!schemaVal) return () => true
-
-    if (parentSchema.format === 'objectid') {
-      return function (value: string, obj: any) {
-        const { parentData, parentDataProperty } = obj
-        parentData[parentDataProperty] = new ObjectId(value)
-        return true
-      }
+const jsonSchema = {
+  type: 'object',
+  properties: {
+    userId: {
+      type: 'string',
+      objectid: true
     }
-    return () => true
   }
-} as const
-
-dataValidator.addKeyword(keywordConvert)
-queryValidator.addKeyword(keywordConvert)
+}
 ```
 
-And then update the shared `ObjectId` in `utilities`:
+<BlockQuote label="Important" type="warning">
 
-```ts
-export const ObjectId = () =>
-  Type.Union([
-    Type.String({ format: 'objectid', convert: true }),
-    Type.Object({}, { additionalProperties: true })
-  ])
-```
+Usually a converted object id property can be treated like a string but in some cases when working with it on the server you may have to call `toString()` to get the proper type.
+
+</BlockQuote>
 
 ### ObjectId resolvers
 

docs/guides/basics/schemas.md

@@ -161,7 +161,7 @@ import { dataValidator, queryValidator } from '../../validators'
 // Main data model schema
 export const userSchema = Type.Object(
   {
-    _id: Type.String(),
+    _id: Type.String({ objectid: true }),
     email: Type.String(),
     password: Type.Optional(Type.String()),
     githubId: Type.Optional(Type.Number()),
@@ -275,7 +275,7 @@ export const messageSchema = Type.Object(
     id: Type.Number(),
     text: Type.String(),
     createdAt: Type.Number(),
-    userId: Type.String(),
+    userId: Type.Number(),
     user: Type.Ref(userSchema)
   },
   { $id: 'Message', additionalProperties: false }
@@ -362,10 +362,10 @@ import { userSchema } from '../users/users.schema'
 // Main data model schema
 export const messageSchema = Type.Object(
   {
-    _id: Type.String(),
+    _id: Type.String({ objectid: true }),
     text: Type.String(),
     createdAt: Type.Number(),
-    userId: Type.String(),
+    userId: Type.String({ objectid: true }),
     user: Type.Ref(userSchema)
   },
   { $id: 'Message', additionalProperties: false }

docs/guides/basics/starting.md

@@ -46,7 +46,7 @@ Since any Feathers application is a Node application, we can create a default [p
 ```sh
 npm init --yes
 # Install TypeScript and its NodeJS wrapper
-npm i typescript ts-node --save-dev
+npm i typescript ts-node @types/node --save-dev
 # Also initialize a TS configuration file that uses modern JavaScript
 npx tsc --init --target es2020
 ```
@@ -217,7 +217,6 @@ Then update `app.ts` with the following content:
 </LanguageBlock>
 <LanguageBlock global-id="js">
 
-
 ```sh
 npm install @feathersjs/socketio@pre @feathersjs/koa@pre koa-static --save
 ```

docs/guides/cli/validators.md

@@ -40,3 +40,7 @@ export const queryValidator = addFormats(
   formats
 )
 ```
+
+## MongoDB ObjectIds
+
+When choosing MongoDB, the validators file will also register the [`objectid` keyword](../../api/databases/mongodb.md#ajv-keyword) to convert strings to MongoDB Object ids.