From 6926e4ea02a5d87e0f2ab37a99b84941c5044353 Mon Sep 17 00:00:00 2001
From: ffrostfall <80861876+ffrostfall@users.noreply.github.com>
Date: Wed, 6 Nov 2024 13:50:13 -0500
Subject: [PATCH] Add metatable-type-syntax.md

---
 docs/metatable-type-syntax.md | 34 ++++++++++++++++++++++++++++++++++
 1 file changed, 34 insertions(+)
 create mode 100644 docs/metatable-type-syntax.md

diff --git a/docs/metatable-type-syntax.md b/docs/metatable-type-syntax.md
new file mode 100644
index 0000000..7e9debc
--- /dev/null
+++ b/docs/metatable-type-syntax.md
@@ -0,0 +1,34 @@
+# Metatable Type Syntax
+
+## Summary
+
+Add unique syntax to allow for specifying the metatable of a type.
+
+## Motivation
+
+There is currently no expression for metatables within the type system, with the exception of hacks using `keyof`. That isn't great, because metatables are a commonly required feature for things like object-oriented programming. `typeof` is boilerplate which can likely be eliminated by allowing the expression of metatables through special syntax.
+
+## Design
+
+Introduce a context-sensitive `metatable` keyword which specifies that a table has a metatable.
+
+```lua
+local class = {}
+type Identity = {
+	field: string,
+
+	metatable typeof(class)
+}
+```
+
+## Alternatives
+
+`type T = { metatable {} }` could be too similar to field syntax. An argument could be made that `type T = { metatable: {} }` is too similar to metatable syntax. We could change the keyword to be `@metatable`, similar to how it is currently expressed as when converting a type to a string. However, this introduces a sigil, which increases cognitive load and harms readability.
+
+Do nothing, and instead rely on [metatable type functions](https://github.com/luau-lang/rfcs/pull/69) to achieve what this RFC proposes. However, relying purely on `setmetatable` for metatable type expression isn't ideal, as it involves more verbose syntax than what this RFC proposes.
+
+Do nothing, and live with the boilerpalte code required by the `typeof` solution.
+
+## Drawbacks
+
+Unique syntax always has the downside of an additional learning curve to the language. Context-sensitive keywords &sigils increase cognitive load when trying to read Luau, which isn't great.