From 26cda48b8ce3c4f8201ccc687da5ec3e9e02637d Mon Sep 17 00:00:00 2001 From: Tom Duncalf Date: Thu, 22 Sep 2022 15:15:16 +0100 Subject: [PATCH] Add table --- packages/babel-plugin/README.md | 82 ++++++++++++++++++- .../src/tests/generator/variants.ts | 2 +- 2 files changed, 81 insertions(+), 3 deletions(-) diff --git a/packages/babel-plugin/README.md b/packages/babel-plugin/README.md index b674dcc8116..a1a34ca6134 100644 --- a/packages/babel-plugin/README.md +++ b/packages/babel-plugin/README.md @@ -62,11 +62,89 @@ export class Task extends Realm.Object { ## Installation -npm start -- --reset-cache +1. Install the `@realm/babel-plugin` npm package: + + `npm install --save-dev @realm/babel-plugin` + +2. If you don't already have it installed, install the `@babel/plugin-proposal-decorators` (only required if you need to use the `@index` or `@mapTo` decorators): + + `npm install --save-dev @babel/plugin-proposal-decorators` + +3. Update your project's `babel.config.js` to load these two plugins: + + ```js + // Existing babel.config.js content is commented out + // module.exports = { + // presets: ['module:metro-react-native-babel-preset'], + + // -------------------------- + // Add the following plugins: + plugins: [ + '@realm/babel-plugin', + ['@babel/plugin-proposal-decorators', { legacy: true }], + ], + // -------------------------- + // }; + + ``` + +4. If using React Native, you may need to clear your packager cache for it to pick up the new plugins: + + `npm start -- --reset-cache` ## Usage -### Supported types +### Defining model properties + +To define your Realm models when using this plugin, simply create classes which extend `Realm.Object`, and define the model's properties using either supported TypeScript types or `Realm.Types` types (see [supported types](#supported-types)). It is recommended that you use the non-null assertion operator (`!`) after the property name, to tell TypeScript that the property will definitely have a value. + +```ts +import Realm from "realm"; + +export class Task extends Realm.Object { + _id!: Realm.BSON.ObjectId; + description!: string; + isComplete!: boolean; + count!: Realm.Types.Int; +} +``` + +You can also import `Object` and `Types` directly from `realm`: + +```ts +import { Object, Types, BSON } from "realm"; + +export class Task extends Object { + _id!: BSON.ObjectId; + description!: string; + isComplete!: boolean; + count!: Types.Int; +} +``` + +#### Supported types + +This plugin supports standard TypeScript types wherever possible, to make defining your model as natural as possible. Some Realm types do not have a direct TypeScript equivalent, or can have more nuance than TypeScript supports (e.g. `double`, `int` and `float` are all represented by `number` in TypeScript), so in these cases you should use the types provided by `Realm.Types` – you can also exclusively use types from `Realm.Types` if preferred. Some Realm types are already exported from the `Realm` namespace and are re-exported by `Realm.Types`, so you can use either variant. + +The supported types are shown in the table below. See [the Realm documentation](https://www.mongodb.com/docs/realm/sdk/react-native/data-types/field-types/) and [SDK documentation](https://www.mongodb.com/docs/realm-sdks/js/latest/Realm.html#~PropertyType) for more details on each type. + +| Realm.Types type | Realm schema type | TypeScript type | Realm type | Notes | +| -------------------------------------------- | ----------------- | --------------- | ----------------------- | -------------------------------------------------------------------------------------- | +| `Types.Bool` | `bool` | `boolean` | | | +| `Types.String` | `string` | `string` | | | +| `Types.Int` | `int` | `number` | | | +| `Types.Float` | `float` | `number` | | | +| `Types.Double` | `double` | `number` | | | +| `Types.Decimal128` | `decimal128` | | `Realm.BSON.Decimal128` | | +| `Types.ObjectId` | `objectId` | | `Realm.BSON.UUID` | | +| `Types.UUID` | `uuid` | | | | +| `Types.Date` | `date` | `Date` | | | +| `Types.Data` | `data` | `ArrayBuffer` | | | +| `Types.List` | `type[]` | | `Realm.List` | `T` is the type of objects in the list | +| `Types.Set` | `type<>` | | `Realm.Set` | `T` is the type of objects in the set | +| `Types.Dictionary` | `type{}` | | `Realm.Dictionary` | `T` is the type of objects in the dictionary | +| `Types.Mixed` | `mixed` | `unknown` | `Realm.Mixed` | | +| Types.LinkingObjects | `linkingObjects` | | | `T` is the type of objects, `N` is the property name of the relationship (as a string) | ## Restrictions diff --git a/packages/babel-plugin/src/tests/generator/variants.ts b/packages/babel-plugin/src/tests/generator/variants.ts index 1993cb0f6bb..ee0dc06d894 100644 --- a/packages/babel-plugin/src/tests/generator/variants.ts +++ b/packages/babel-plugin/src/tests/generator/variants.ts @@ -48,7 +48,7 @@ const TYPE_NAME_VARIANTS: Record = { list: ["Realm.List", "Realm.Types.List", "Types.List", "List"], set: ["Realm.Set", "Realm.Types.Set", "Types.Set", "Set"], dictionary: ["Realm.Dictionary", "Realm.Types.Dictionary", "Types.Dictionary", "Dictionary"], - mixed: ["Realm.Mixed", "Mixed"], + mixed: ["Realm.Types.Mixed", "Types.Mixed", "Realm.Mixed", "Mixed"], }; const DEFAULT_INFERABLE_TYPES = new Set([