Skip to content

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.md
index 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` decl
Types 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.gjs
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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 {};