{"id":"fadeluc-123/oak","name":"oak","scope":"fadeluc-123","platform":"roblox","description":"Typed service/controller framework for Roblox on Volt: full Luau inference, typed peers by name, server-authoritative lifecycle.","version":"1.0.0","latest":"1.0.0","versions":["1.0.0"],"license":"Apache-2.0","licenseRating":"safe","licenseCaveats":["Modified files must carry a notice of changes. If the package ships a NOTICE file, its attributions must be preserved."],"licenseVerified":true,"dependencies":{"evaera/promise":{"version":"^4.0.0","alias":"Promise"},"fadeluc-123/volt":{"version":"^0.1.0","alias":"Volt"}},"integrity":"089a4cf54e803986f9d04850f4d1ac1c97be9f99f1c2981e6036c7a4e8b8376f","likes":0,"downloads":0,"install":"forest install fadeluc-123/oak","url":"https://forest.dev/p/roblox/fadeluc-123/oak","files":"https://api.forest.dev/ai/package/roblox/fadeluc-123/oak/files","readme":"# Oak\n\nOak is Whiteoak Studios' service and controller framework for Roblox, the replacement for the archived Knit. A game writes its server code as services and its client code as controllers, plain tables made with `Oak.create`, and boots each realm with `Oak.start`. Every message between the realms goes through [Volt](https://github.com/Fadeluc-123/Volt), Whiteoak's buffer networking package, which owns everything on the wire: the schema, validation, rate limits and failure reports. Oak adds no networking of its own. It binds each service's handlers to the endpoints the game's Volt schema declares and refuses to boot when the two disagree, runs every `Init` and then every `Start`, routes each Volt failure to the table that owns the message or to a game-wide handler, and replicates state through `Oak.Property`. Knit typed every service `{ [any]: any }`, so nothing that touched one autocompleted. `Oak.create` returns the table it was given with its type unchanged, so every method, field and `Client` member stays typed in every file that reaches it, a peer reached by name included. Oak's types are written for luau-lsp's new type checker.\n\n## Install\n\n### `wally.toml`\n\n```toml\n[dependencies]\nOak = \"fadeluc-123/oak@^1.0.0\"\nPromise = \"evaera/promise@4.0.0\"\nVolt = \"fadeluc-123/volt@0.1.0\"\n```\n\nOak depends on Promise and Volt itself, and a game lists both as well. Its generated network modules require `ReplicatedStorage.Packages.Volt` and, under `option yield = promise`, `ReplicatedStorage.Packages.Promise`, and Wally only puts a top-level dependency at those paths.\n\nKeep the game's `Volt` on Oak's Volt line, `0.1.x` for Oak 1.0.0. `Oak.start` compares the Volt that compiled the game's network module with the Volt installed with Oak and refuses to boot, naming both versions, when their major.minor differ. Wally installs two Volt lines side by side without complaint, so that check is what catches a mismatch. The `volt` compiler comes from Volt's GitHub Releases through Rokit, on the same line: `rokit add fadeluc-123/volt`.\n\n### The typed install\n\nA Wally thunk in `Packages/` drops every `export type` of the package it points at, so after a plain `wally install`, `require(Packages.Oak)` is `any` and none of Oak's types reach the game. After every install, run these three in this order:\n\n```sh\nwally install\nrojo sourcemap sourcemap.project.json --output sourcemap.json\nwally-package-types --sourcemap sourcemap.json Packages/\n```\n\nThe project file is the game's sourcemap project, `sourcemap.project.json` in a Whiteoak game (`dev.project.json` in a package repo). `wally-package-types` 1.6.2 exits 1 on a second pass over links it has already typed, so it runs once after each fresh `wally install`. A Lune script in `.lune/` is a good home for the three.\n\n### The new type checker\n\nOak is written for luau-lsp's new type checker, `LuauSolverV2`. luau-lsp's command line runs the old checker unless told otherwise, so every `luau-lsp analyze` passes `--flag:LuauSolverV2=true`:\n\n```sh\nluau-lsp analyze --platform=roblox --flag:LuauSolverV2=true --sourcemap=sourcemap.json --definitions=globalTypes.d.luau --ignore=\"Packages/**\" src\n```\n\n`globalTypes.d.luau` is `scripts/globalTypes.d.luau` from luau-lsp's repository. The editor runs the same checker with these three lines in `.vscode/settings.json`, beside the `luau-lsp.sourcemap.rojoProjectFile` line that names the sourcemap project:\n\n```json\n{\n\t\"luau-lsp.fflags.enableNewSolver\": true,\n\t\"luau-lsp.fflags.enableByDefault\": true,\n\t\"luau-lsp.fflags.sync\": false\n}\n```\n\nThe first turns the new checker on, the second turns on every boolean Luau flag the way `luau-lsp analyze` does, and the third stops the extension copying Roblox's live Luau flags. Without the sourcemap line, luau-lsp builds no sourcemap, every instance-path require resolves to `any`, and Oak's typing is invisible.\n\n### One `.luaurc` per mode\n\nA peer's type is written through two aliases, so each mode folder (`src/game/`, `src/lobby/` and the rest) holds a `.luaurc` beside the root one that sets strict mode:\n\n```json\n{\n\t\"aliases\": {\n\t\t\"Services\": \"./Server/Services\",\n\t\t\"Controllers\": \"./Client/Services\"\n\t}\n}\n```\n\nThe aliases only shorten the path inside `typeof(require(...))`, which sits in a type position and never runs, and every require that runs keeps its instance path. A mode other than Game that names a peer it maps in from `src/game` also adds `@GameServices` and `@GameControllers`, pointing at `src/game`'s two folders, and types that peer through them, since an alias is read from the `.luaurc` nearest the file.\n\n## A first look\n\nOne endpoint, the service that answers it, the controller that calls it, and the boot. The schema, `src/game/Schemas/Greeter.volt`:\n\n```\nnamespace Greeter {\n\tfunction greet {\n\t\treturn: string(0..64),\n\t}\n}\n```\n\n`src/game/Server/Services/Features/GreeterService.luau`, below its header and requires:\n\n```lua\nlocal Service = Oak.create(\"GreeterService\", {\n\tClient = {},\n\n\tPolicy = {\n\t\tgreet = { rate = { perSecond = GREET_RATE } },\n\t},\n\n\t_greeted = 0, -- Greetings answered on this server\n})\n\nfunction Service.greet(self: Self, player: Player): string\n\tself._greeted += 1\n\treturn `Hello, {player.Name}! That's greeting {self._greeted} on this server`\nend\n\nfunction Service.Client:greet(player: Player): string\n\treturn (Service :: Self):greet(player)\nend\n\nfunction Service:Start() end\nfunction Service:Init() end\n\ntype Self = typeof(Service)\n\nreturn Service\n```\n\n`src/game/Client/Services/Features/GreeterController.luau`, below its header and requires:\n\n```lua\nlocal Controller = Oak.create(\"GreeterController\", {\n\t_greeting = nil :: string?, -- What the server greeted us with\n})\n\nfunction Controller:Init() end\nfunction Controller.Start(self: Self)\n\tNetwork.Greeter.greet\n\t\t.invoke()\n\t\t:andThen(function (greeting: string)\n\t\t\tself._greeting = greeting\n\t\t\tprint(greeting)\n\t\tend)\n\t\t:catch(warn)\nend\n\ntype Self = typeof(Controller)\n\nreturn Controller\n```\n\nEach realm's bootstrap requires its generated module, `Network.Server` here and `Network.Client` on the client, and after the component hoist shown under [Lifecycle and boot](#lifecycle-and-boot), starts its `Services` folder:\n\n```lua\nlocal Network = require(ReplicatedStorage.Shared.Network.Server) -- Volt-generated, this mode's module set\n\nOak.start(script.Services, Network)\n```\n\n`GreeterService` owns the `Greeter` namespace because its name is `Greeter` plus `Service`. The schema line, the `Client` handler and the `Policy` row must all exist: leave any one out and `Oak.start` refuses to boot, naming the endpoint.\n\n## Using Oak\n\nThe snippets below are one small Game mode, laid out the way a Whiteoak game is. Like a Whiteoak game, it installs sleitnick's Observers (`sleitnick/observers`), which clears each player's records when they leave; Observers is the game's dependency, not Oak's.\n\n```\nsrc/game/\n├── .luaurc                       -- @Services and @Controllers\n├── Schemas/                      -- Game.volt (the options), Greeter.volt, Shop.volt, Inventory.volt\n├── Server/\n│   ├── init.server.luau\n│   ├── Config/                   -- Greeter, Inventory, Moderation\n│   └── Services/\n│       ├── Features/             -- GreeterService, ShopService, InventoryService\n│       └── Player/               -- ModerationService\n├── Client/\n│   ├── init.client.luau\n│   ├── Components/Shop Counter.luau\n│   └── Services/Features/        -- GreeterController, ShopController, InventoryController, NotificationController\n└── Shared/\n    ├── Config/Shop.luau\n    ├── Config/Types/Shop.luau\n    └── Network/                  -- Volt's output: Server.luau, Client.luau, Types.luau\n```\n\n`Shop.volt`, which every snippet below leans on:\n\n```\nnamespace Shop {\n\t-- Each player's balance: state a late joiner must receive, so an Oak.Property\n\tevent coins {\n\t\tfrom: Server, type: Reliable, call: SingleAsync,\n\t\tdata: u32,\n\t}\n\n\t-- A one-shot notification, so a plain event and never a Property\n\tevent purchased {\n\t\tfrom: Server, type: Reliable, call: ManyAsync,\n\t\tdata: (itemId: string(1..32), remaining: u32),\n\t}\n\n\t-- ShopService's Policy row replaces this rate at bind, so it never applies\n\tfunction purchase {\n\t\tdata: (itemId: string(1..32)),\n\t\treturn: (ok: boolean, reason: string(0..128)?),\n\t\trate: 4,\n\t}\n\n\t-- The server offers a player an item, and ShopController answers whether they can afford it\n\tfunction offer {\n\t\tfrom: Server,\n\t\tdata: (itemId: string(1..32), price: u32),\n\t\treturn: boolean,\n\t}\n}\n```\n\n### Services and controllers\n\nA service is a table made with `Oak.create`. `src/game/Server/Services/Features/ShopService.luau`:\n\n```lua\n--[[\n    The shop: prices each item, takes coins for a purchase and hands the item\n    to InventoryService, replicating each player's balance through a Property.\n    Owns the Shop namespace, so every Shop endpoint and failure lands here\n--]]\n\n--!strict\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal Packages = ReplicatedStorage.Packages\n\nlocal Oak = require(Packages.Oak)\nlocal Volt = require(Packages.Volt)\n\nlocal Network = require(ReplicatedStorage.Shared.Network.Server)\n\nlocal InventoryService: typeof(require(\"@Services/Features/InventoryService\")) = Oak.getService(\"InventoryService\")\n\nlocal PRICES: { [string]: number } = require(ReplicatedStorage.Shared.Config.Shop).prices\nlocal PURCHASE_BURST: number = require(ReplicatedStorage.Shared.Config.Shop).purchaseBurst\nlocal PURCHASE_RATE: number = require(ReplicatedStorage.Shared.Config.Shop).purchaseRate\nlocal STARTING_COINS: number = require(ReplicatedStorage.Shared.Config.Shop).startingCoins\n\ntype Bot = Volt.Bot\n\nlocal Service = Oak.create(\"ShopService\", {\n\tClient = {\n\t\tcoins = Oak.Property(Network.Shop.coins, STARTING_COINS), -- Coin balance, per player\n\t},\n\n\tPolicy = {\n\t\tpurchase = { rate = { perSecond = PURCHASE_RATE, burst = PURCHASE_BURST } },\n\t},\n\n\t_prices = PRICES, -- What each item costs\n\t_sales = {} :: { [string]: number }, -- Units sold per item id on this server\n})\n\n--[[\n    What an item costs, or nil for an item the shop doesn't sell\n--]]\n\nfunction Service.price(self: Self, itemId: string): number?\n\treturn self._prices[itemId]\nend\n\n--[[\n    Buys an item for a player: checks the price against their balance, puts\n    the item in their inventory, then takes the coins. A refusal the player\n    should read comes back as the reason\n--]]\n\nfunction Service.purchase(self: Self, player: Player, itemId: string): (boolean, string | nil)\n\tlocal price: number? = self:price(itemId)\n\tif not price then\n\t\treturn false, `Unknown item: {itemId}`\n\tend\n\n\tlocal coins: number = self.Client.coins:GetFor(player)\n\tif coins < price then\n\t\treturn false, `Not enough coins`\n\tend\n\n\tlocal inserted: boolean, reason: string? = InventoryService:insert(player, itemId)\n\tif not inserted then\n\t\treturn false, reason\n\tend\n\n\tlocal remaining: number = coins - price\n\tself._sales[itemId] = (self._sales[itemId] or 0) + 1\n\n\t-- State through the Property, the notification through its own event\n\tself.Client.coins:SetFor(player, remaining)\n\tNetwork.Shop.purchased.fire(player, itemId, remaining)\n\n\treturn true, nil\nend\n\nfunction Service.Client:purchase(player: Player, itemId: string): (boolean, string | nil)\n\treturn (Service :: Self):purchase(player, itemId)\nend\n\n--[[\n    Pays a player coins, for an item they sold back\n--]]\n\nfunction Service.pay(self: Self, player: Player, coins: number)\n\tself.Client.coins:SetFor(player, self.Client.coins:GetFor(player) + coins)\nend\n\n--[[\n    Sends a player's balance again even though it hasn't changed, for a\n    client that rebuilt its interface and lost what it had\n--]]\n\nfunction Service.resync(self: Self, player: Player)\n\tself.Client.coins:Refresh(player)\nend\n\n--[[\n    Every Volt failure on a Shop message lands here instead of the game-wide\n    handler, a purchase past the Policy row's rate among them\n--]]\n\nfunction Service.onFailure(player: Player | Bot, kind: string, detail: string)\n\twarn(`Shop {kind} failure from {player.Name}: {detail}`)\nend\n\nfunction Service:Start() end\nfunction Service.Init(self: Self)\n\tself.Client.coins:SetTop(STARTING_COINS)\nend\n\ntype Self = typeof(Service)\n\nreturn Service\n```\n\n- `Oak.create(name, def)` takes the table's name first; the table itself has no `Name` field. The name is the registry name peers resolve by and loader errors and memory categories report, and by convention it matches the file name. The table's Volt namespace is that name less a trailing `Service` or `Controller`, so `ShopService` owns `namespace Shop`. `Oak.create(def)` with no name also works and takes the ModuleScript's name, with a warning at boot. Creating one table twice is an error.\n- `create` returns the same table with its type unchanged, so methods, `Client` handlers, `onFailure`, `Init` and `Start` are added after the call, and any file that types this module autocompletes `:purchase`, `.Client.coins` and `._sales`.\n- Oak reads five keys from the table: `Client`, `Policy`, `Init`, `Start` and `onFailure`. Every other key, such as `_sales`, is the service's own. A field whose first value is narrower than its type carries a cast in the literal, as `_sales` does.\n- A method whose body uses `self` is defined with a dot and an annotated `self: Self`, called with a colon, and reaches the table through `self`, never through `Service`: the new checker checks neither the arguments nor the return of a call through the table's own local inside a function body. `type Self = typeof(Service)` is the last statement before the return: written directly after the create, it would leave the new checker unable to check calls through `self`.\n- A `Client` handler is the one exception. The binder calls it with a colon, so its `self` is the `Client` table, and it sits directly under the method it wraps, names the player and forwards through the cast `(Service :: Self)`, which both checkers check fully.\n- Both lifecycle methods are always written. An empty one keeps the colon on one line and goes first, directly above the one with a body, which takes the dot form. `GreeterService` above has both empty.\n- Every service and controller file requires its realm's generated module as `Network` and calls handles through it, so each call is checked in the editor. A failure a service must report is a `(boolean, string | nil)` tuple, and every return path gives both values.\n\nA controller is made the same way, with no `Client` and no `Policy`: the client's boot refuses a table with either. `src/game/Client/Services/Features/ShopController.luau`:\n\n```lua\n--[[\n    The client half of the shop: the balance the server replicates, a toast\n    for each purchase it confirms, buying through the Shop namespace and an\n    answer to every item the server offers\n--]]\n\n--!strict\nlocal ReplicatedStorage = game:GetService(\"ReplicatedStorage\")\nlocal Packages = ReplicatedStorage.Packages\n\nlocal Oak = require(Packages.Oak)\n\nlocal Network = require(ReplicatedStorage.Shared.Network.Client)\n\nlocal NotificationController: typeof(require(\"@Controllers/Features/NotificationController\")) =\n\tOak.getController(\"NotificationController\")\n\nlocal Controller = Oak.create(\"ShopController\", {\n\tcoins = Oak.Property(Network.Shop.coins), -- This player's coin balance\n})\n\n--[[\n    Whether the player can afford a price right now: false until the first\n    balance has arrived, rather than waiting for it\n--]]\n\nfunction Controller.canAfford(self: Self, price: number): boolean\n\tlocal coins: number? = self.coins:Get()\n\treturn coins ~= nil and coins >= price\nend\n\n--[[\n    Asks the server to buy an item the player can afford, and toasts the\n    reason for any refusal, whether the shop's or Volt's\n--]]\n\nfunction Controller.purchase(self: Self, itemId: string, price: number)\n\tif not self:canAfford(price) then\n\t\treturn NotificationController:show(`Not enough coins for {itemId}`)\n\tend\n\n\tNetwork.Shop.purchase\n\t\t.invoke(itemId)\n\t\t:andThen(function (ok: boolean, reason: string?)\n\t\t\tif not ok then\n\t\t\t\tNotificationController:show(`Purchase refused: {reason}`)\n\t\t\te","readmeTruncated":true,"readmeFull":"https://api.forest.dev/v1/package/fadeluc-123/roblox/oak/1.0.0/readme"}