A platform for community discussion. Free, open, simple.
DEV: Document typing model fields added by plugins (#45162)
Sérgio Saquetim83aefa788cad
diff --git a/docs/developer-guides/docs/03-code-internals/27-types.md b/docs/developer-guides/docs/03-code-internals/27-types.mdindex a71bf754fa0..cee7eb33b6e 100644--- a/docs/developer-guides/docs/03-code-internals/27-types.md+++ b/docs/developer-guides/docs/03-code-internals/27-types.md@@ -22,6 +22,37 @@ JavaScript files are not type-checked, but the published `@discourse/types` declTypes whose meaning a runtime test can't capture (a generic's resolved type, an overload pick, a return type derived from arguments) can be asserted at compile time with [`expect-type`](https://github.com/mmkal/expect-type), in `.ts`/`.gts` files under `frontend/discourse/type-tests/` (e.g. `type-tests/truth-helpers/`). They are checked by `pnpm lint:types` but kept out of the test and production bundles.+## Typing model fields added by plugins++Converted models declare the fields core sends in an interface named after the model: `TopicFields`, `CategoryFields`, `SiteFields` and `UserDraftFields`. A plugin that adds fields, on the server with `add_to_serializer` or on the client with `api.addModelField` or `api.addTrackedTopicProperties`, can declare them by augmenting that interface.++The store has two registries that work the same way. `ModelRegistry` maps a store type name to its model, so `store.find` and `store.createRecord` return that model. `ModelCreateAttrsRegistry` maps a type name to the attributes `createRecord` accepts, for models whose inputs differ from their fields.++```ts+// plugins/my-plugin/assets/javascripts/discourse/model-types.ts+import type Sticker from "./models/sticker.js";++declare module "discourse/models/topic" {+ interface TopicFields {+ /** Sent only when the topic has stickers. */+ sticker_count?: number;+ }+}++declare module "discourse/services/store" {+ interface ModelRegistry {+ sticker: Sticker;+ }+}+```++With this file in place, `topic.sticker_count` is a `number | undefined`, and `store.createRecord("sticker")` returns a `Sticker`.++- Type each field from what the server sends. Make it optional unless every payload that builds the model includes it, and add `| null` when the serializer can return `nil`.+- The file must be a module, so keep at least one `import type` or an `export {};`. Without one, the `declare module` blocks replace the core modules instead of extending them. Avoid a bare `import "discourse/models/topic";` for this, because it stays in the bundle as a runtime import.+- Use a `.ts` file, not `.d.ts`. Type checking skips declaration files, so a field that clashes with the type core declares is only reported from a `.ts` file. The file compiles to an empty module.+- Key the registries by the exact string the plugin passes to the store. Names that aren't registered fall back to `RestModel`.+## Usage- **CLI**: Run `pnpm lint:types`diff --git a/frontend/discourse/app/lib/plugin-api.gjs b/frontend/discourse/app/lib/plugin-api.gjsindex b243448b5e6..06413c231b2 100644--- a/frontend/discourse/app/lib/plugin-api.gjs+++ b/frontend/discourse/app/lib/plugin-api.gjs@@ -821,6 +821,10 @@ class _PluginApi {* You'll need to do this if you've added properties to a Topic and need them to be* automatically updated in the UI when there are changes in the model.*+ * To type the properties for TypeScript, augment `TopicFields` from+ * `discourse/models/topic`, as described in the "JS type hinting &+ * validation" developer guide.+ ** @param {...string} names - The names of the properties to be tracked.*/addTrackedTopicProperties(...names) {@@ -833,6 +837,10 @@ class _PluginApi {** Must be called from a pre-initializer, before the model is first looked up.*+ * To type the field for TypeScript, augment the model's fields interface,+ * such as `TopicFields` from `discourse/models/topic`, as described in the+ * "JS type hinting & validation" developer guide.+ ** @param {string} modelName - The model's resolver name, e.g. "bookmark".* @param {string} name - The name of the field to add.* @param {Object} [options]diff --git a/frontend/discourse/app/models/topic.ts b/frontend/discourse/app/models/topic.tsindex e3b3520d9f0..5329c52c688 100644--- a/frontend/discourse/app/models/topic.ts+++ b/frontend/discourse/app/models/topic.ts@@ -46,7 +46,7 @@ import type User from "discourse/models/user";import type AppEventsService from "discourse/services/app-events";import { flushMap } from "discourse/services/store";import { i18n } from "discourse-i18n";-import Category from "./category.ts";+import Category, { type CategoryFields } from "./category.ts";/** A tag attached to a topic. */export interface TopicTag {@@ -133,7 +133,7 @@ export interface TopicFields {bumped?: boolean;bumped_at?: string;can_localize_topic?: true;- categories?: object[];+ categories?: CategoryFields[];category_id?: number | null;chunk_size?: number;closed?: boolean;diff --git a/frontend/discourse/type-tests/models/topic-test.ts b/frontend/discourse/type-tests/models/topic-test.tsindex 7b16307133e..dd7e04a8f98 100644--- a/frontend/discourse/type-tests/models/topic-test.ts+++ b/frontend/discourse/type-tests/models/topic-test.ts@@ -3,7 +3,10 @@ import { expectTypeOf } from "expect-type";import type ActionSummary from "discourse/models/action-summary";import type Archetype from "discourse/models/archetype";import type Bookmark from "discourse/models/bookmark";-import type Category from "discourse/models/category";+import type {+ CategoryFields,+ default as Category,+} from "discourse/models/category";import type Post from "discourse/models/post";import type PostStream from "discourse/models/post-stream";import type PublishedPage from "discourse/models/published-page";@@ -134,7 +137,7 @@ interface ExpectedTopicFields {bumped?: boolean;bumped_at?: string;can_localize_topic?: true;- categories?: object[];+ categories?: CategoryFields[];category_id?: number | null;chunk_size?: number;closed?: boolean;diff --git a/plugins/discourse-data-explorer/assets/javascripts/discourse/model-types.ts b/plugins/discourse-data-explorer/assets/javascripts/discourse/model-types.tsnew file mode 100644index 00000000000..1dd8c80833b--- /dev/null+++ b/plugins/discourse-data-explorer/assets/javascripts/discourse/model-types.ts@@ -0,0 +1,7 @@+import type Query from "./models/query.js";++declare module "discourse/services/store" {+ interface ModelRegistry {+ query: Query;+ }+}diff --git a/plugins/discourse-topic-voting/assets/javascripts/discourse/model-types.ts b/plugins/discourse-topic-voting/assets/javascripts/discourse/model-types.tsnew file mode 100644index 00000000000..0a74008db19--- /dev/null+++ b/plugins/discourse-topic-voting/assets/javascripts/discourse/model-types.ts@@ -0,0 +1,19 @@+declare module "discourse/models/topic" {+ interface TopicFields {+ /** Omitted from topic lists for topics that aren't regular topics. */+ can_vote?: boolean;+ /** Omitted from topic lists for topics that can't be voted on. */+ vote_count?: number;+ /** Null in topic lists for anonymous users. */+ user_voted?: boolean | null;+ }+}++declare module "discourse/models/category" {+ interface CategoryFields {+ /** Sent only for categories that allow voting. */+ can_vote?: true;+ }+}++export {};