Flamework v1.2.0 release

blog/2024-03-21-flamework-release.md

@@ -0,0 +1,51 @@
+---
+title: Flamework v1.2.0
+authors: fireboltofdeath
+tags: [Release]
+---
+
+## Change Log
+
+[@flamework/core](https://github.com/rbxts-flamework/core/commits/master)
+[@flamework/components](https://github.com/rbxts-flamework/components/commits/master)
+[@flamework/networking](https://github.com/rbxts-flamework/networking/commits/master)
+[rbxts-transformer-flamework](https://github.com/rbxts-flamework/transformer/commits/master)
+
+## Additions
+
+### Core
+- Fixed the `constructor` field always being `undefined` on decorator descriptors.
+
+### Networking
+- Fixed a bug where Flamework would always create both a reliable and unreliable remote.
+
+### Transformer
+- [Reflection support for roblox-ts decorators.](#roblox-ts-decorators)
+- Added support for nominal fields in guard generation.
+	- This means types like `string & { _nominal_mynominalfield: never }` will become just `t.string`
+- Fixed bug that triggered a diagnostic when extending a user macro class.
+- Fix crash when generating guards with an `unknown` field.
+
+<!-- truncate -->
+
+## Changes
+
+### roblox-ts decorators
+Flamework now supports reflection for native roblox-ts decorators, and they can be used in place (or alongside) of Flamework decorators.
+
+By default, Flamework will ignore roblox-ts decorators but you can specify the `@metadata reflect` JSDoc to enable Flamework's reflection.
+Unlike Flamework decorators, roblox-ts decorators with the `reflect` metadata do not automatically generate *any* metadata, including the `identifier` metadata, which must be specified manually.
+
+```ts
+/** @metadata reflect identifier flamework:parameters */
+const NewDecorator = (ctor: unknown) => {};
+
+@NewDecorator
+class MyClass {
+	constructor(a: string) {}
+}
+```
+
+As a caveat, you cannot currently use roblox-ts decorators with Flamework's modding API (listeners, `getDecorator`, `getDecorators`, `getPropertyDecorators`, etc.)
+
+Support for these APIs may be added in a future update but can be implemented fairly easily without Flamework.

docs/modding/guides/decorators.md

@@ -6,6 +6,21 @@ This guide is for creating a custom decorator.
 It is recommended to use native roblox-ts decorators unless you need Flamework behavior, such as access to the modding decorator APIs.
 
 ## Defining the decorator
+Flamework supports both native roblox-ts decorators and its own built-in decorator system.
+
+roblox-ts decorators give you the most control and allow you to use things like generics or user macros, but they do not support the following Modding APIs: listeners, `getDecorator`, `getDecorators` and `getPropertyDecorators`.
+
+### roblox-ts decorators
+Flamework supports reflection for native roblox-ts decorators using the `@metadata reflect` metadata.
+
+Unlike Flamework decorators, `identifier` is not generated by default and must be specified under `@metadata`.
+
+```ts
+/** @metadata reflect identifier flamework:parameters */
+const NewDecorator = (ctor: unknown) => {};
+```
+
+### Flamework decorators
 Flamework has two kinds of decorators, meta decorators and normal decorators.
 
 All Flamework decorators add the metadata necessary for the modding API, however, normal decorators also allow you to run a custom function afterwards. This function is passed information about where it was applied as well as the arguments passed into it.

docs/modding/metadata.md

@@ -73,6 +73,11 @@ Classes with constructors also support all [method metadata](#method-metadata).
 
 ---
 
+### identifier
+This generates the `identifier` metadata which is a unique identifier that refers specifically to this class.
+
+This is only necessary on roblox-ts decorators as Flamework decorators automatically include this metadata.
+
 ### flamework:implements `string[]`
 :::info
 This metadata is required for lifecycle events. If you want to use lifecycle events, you must request this metadata.