@seriousgaming/sdk-tools 0.0.0-stage → 1.0.0-alpha.2

package/dist/docs/guides/type-safety.md

@@ -0,0 +1,516 @@
+# Type safety best practices
+
+This guide ensures you create proper types and avoid common type safety pitfalls when building Serious Gaming games.
+
+## Core principle
+
+The Serious Gaming SDK uses TypeScript and JSON Schema to provide **end-to-end type safety**. When you define a capability's `variablesSchema` or a settings resource's `settingsSchema`, the SDK generates precise TypeScript types. Shortcuts and workarounds (using `any`, string-based JSON, etc.) break this guarantee and lead to runtime errors.
+
+## Rule 1: never use `any` type
+
+The generated types in your `types.ts` file are precise and auto-generated. Always use them:
+
+### ❌ WRONG: using `any`
+
+```typescript
+// types.ts (auto-generated)
+export type Context = {
+  "pricing": {
+    BasePrice: number;
+    CurrentPrice: number;
+  };
+};
+
+export type Settings = {
+  pricing: {
+    PriceAdjustment: number;
+  };
+};
+
+// logic.ts
+// ❌ WRONG
+const { BasePrice }: any = context.pricing;
+const { PriceAdjustment }: any = settings.pricing;
+
+export const Run: RunFunction<any, any> = async ({ context, settings, callbacks }) => {
+  // No type checking, no IDE help, runtime errors likely
+  ...
+};
+```
+
+### ✅ CORRECT: using generated types
+
+```typescript
+// logic.ts
+import type { Context, Settings } from './types';
+import { RunFunction } from '@seriousgaming/sdk';
+
+// ✅ CORRECT
+export const Run: RunFunction<Context, Settings> = async ({ context, settings, callbacks }) => {
+    // Full type safety
+    const { BasePrice, CurrentPrice } = context.pricing;
+    const { PriceAdjustment } = settings.pricing;
+
+    // TypeScript catches errors:
+    // const newPrice = BasePrice + settings.pricing.InvalidField; // Error!
+    // const price = CurrentPrice.toUpperCase(); // Error! (not a string)
+
+    return {
+        capabilities: {
+            ...context,
+            pricing: {
+                ...context.pricing,
+                CurrentPrice: BasePrice + PriceAdjustment,
+            },
+        },
+    };
+};
+```
+
+## Rule 2: use proper JSON Schema types
+
+Match your schema type to the actual data. Never use `string` as a workaround for complex data.
+
+### ❌ WRONG: string type for complex data
+
+```bash
+# ❌ WRONG: Accepting JSON as string
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "policy",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "Rules": {
+          "type": "string",
+          "default": "{\"taxRate\": 0.1, \"enabled\": true}"
+        }
+      },
+      "required": ["Rules"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+```typescript
+// ❌ WRONG: Parsing JSON from string at runtime
+const rules = JSON.parse(context.policy.Rules);
+const taxRate = rules.taxRate; // String parsing, no type safety
+```
+
+### ✅ CORRECT: object type for complex data
+
+```bash
+# ✅ CORRECT: Use object type
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "policy",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "Rules": {
+          "type": "object",
+          "properties": {
+            "taxRate": { "type": "number", "minimum": 0, "maximum": 1 },
+            "enabled": { "type": "boolean" }
+          },
+          "required": ["taxRate", "enabled"],
+          "additionalProperties": false,
+          "default": { "taxRate": 0.1, "enabled": true },
+          "description": "Tax rules"
+        }
+      },
+      "required": ["Rules"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+```typescript
+// ✅ CORRECT: Access as typed object
+const { Rules } = context.policy;
+const taxRate = Rules.taxRate; // Type-safe, IDE autocomplete
+```
+
+The generated type will be:
+
+```typescript
+export interface Context {
+    policy: {
+        Rules: {
+            taxRate: number;
+            enabled: boolean;
+        };
+    };
+}
+```
+
+### Where a precise type comes from
+
+The generator reads the type from the schema's keywords, never from `default`. A `default` seeds the tick-0 value and nothing more, so `{ "type": "object", "default": { "taxRate": 0.1 } }` with no `properties` generates `{ [k: string]: unknown }`, and `{ "type": "array", "default": [...] }` with no `items` generates `unknown[]`, however much structure the default shows.
+
+| Schema                                                        | Generated type                                 |
+| ------------------------------------------------------------- | ---------------------------------------------- |
+| `"type": "number"` (or `string`, `boolean`)                   | `number` (or `string`, `boolean`)              |
+| `"enum": ["low", "high"]`                                     | `'low' \| 'high'`                              |
+| `"const": "v1"`                                               | `'v1'`                                         |
+| `"type": "object"` with `properties` and `required`           | An object type with those fields               |
+| The same, plus `"additionalProperties": false`                | The same, with no `[k: string]: unknown` added |
+| `"type": "array"` with `items`                                | An array of the item's type                    |
+| `"type": "object"` or `"type": "array"` with only a `default` | `{ [k: string]: unknown }` or `unknown[]`      |
+
+Set `"additionalProperties": false` on every nested object, not only the top-level schema: without it the object's type gains an index signature, `[k: string]: unknown`, and a misspelt field compiles. Where the schema cannot say what you mean, name a TypeScript type with [`tsType`](./capabilities.md#a-typescript-type-of-your-own).
+
+## Rule 3: define array element types clearly
+
+An array's element type comes from its `items` schema. Without one the array is `unknown[]`, whatever its `default` holds:
+
+### ❌ WRONG: empty array with no type info
+
+```bash
+# ❌ WRONG: No items schema, so the elements are unknown
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "transactions",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "Entries": {
+          "type": "array",
+          "default": []
+        }
+      },
+      "required": ["Entries"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+```typescript
+// At runtime, you don't know what's in the array
+const entries = context.transactions.Entries;
+entries.push('something'); // TypeScript won't catch type errors here
+```
+
+### ✅ CORRECT: define array item schema
+
+```bash
+# ✅ CORRECT: Define item structure in schema, not just default
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "transactions",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "Entries": {
+          "type": "array",
+          "items": {
+            "type": "object",
+            "properties": {
+              "id": { "type": "number" },
+              "amount": { "type": "number", "minimum": 0 },
+              "date": { "type": "string" }
+            },
+            "required": ["id", "amount", "date"],
+            "additionalProperties": false
+          },
+          "default": [
+            { "id": 1, "amount": 100, "date": "2024-01-01" }
+          ],
+          "description": "List of transaction records"
+        }
+      },
+      "required": ["Entries"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+```typescript
+// Now the type is precise
+const entries = context.transactions.Entries;
+// TypeScript infers: Array<{ id: number; amount: number; date: string }>
+entries.push({ id: 2, amount: 50, date: '2024-01-02' }); // Type-checked
+// entries.push({ id: "invalid" }); // Error! Wrong type
+```
+
+## Rule 4: use constraints for validation
+
+JSON Schema supports numeric constraints. Declare them, so the range is written down where every resource can see it (and, in a `settingsSchema`, a scenario or session override outside it is refused). They do not clamp what logic computes: the runtime does not check a value your engine returns against `minimum` or `maximum`, so logic that can push a value out of range still bounds it:
+
+### ❌ WRONG: no constraints, manual validation
+
+```bash
+# ❌ WRONG: No constraints defined
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "pricing",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "Price": {
+          "type": "number",
+          "default": 100
+        }
+      },
+      "required": ["Price"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+```typescript
+// ❌ WRONG: Manual validation in code
+export const Run: RunFunction<Context, Settings> = async ({ context, settings, callbacks }) => {
+    let newPrice = context.pricing.Price + settings.pricing.Adjustment;
+
+    // The range lives only in code: nothing in the schema says what it is
+    if (newPrice < 0) newPrice = 0;
+    if (newPrice > 1000) newPrice = 1000;
+
+    return {/* ... */};
+};
+```
+
+### ✅ CORRECT: constraints in schema
+
+```bash
+# ✅ CORRECT: Define constraints in schema
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "pricing",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "Price": {
+          "type": "number",
+          "default": 100,
+          "minimum": 0,
+          "maximum": 1000,
+          "description": "Product price in dollars"
+        },
+        "TaxRate": {
+          "type": "number",
+          "default": 0.1,
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Tax rate as decimal (0.1 = 10%)"
+        }
+      },
+      "required": ["Price", "TaxRate"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+```typescript
+// ✅ CORRECT: The schema declares the range, and the engine keeps its result inside it
+export const Run: RunFunction<Context, Settings> = async ({ context, settings, callbacks }) => {
+    // The runtime does not clamp returned values to `minimum` / `maximum`
+    const newPrice = Math.min(
+        1000,
+        Math.max(0, context.pricing.Price + settings.pricing.Adjustment)
+    );
+
+    return {
+        capabilities: {
+            ...context,
+            pricing: {
+                ...context.pricing,
+                Price: newPrice,
+            },
+        },
+    };
+};
+```
+
+## Rule 5: never cast away type safety
+
+Avoid `as` casts. They defeat the purpose of typing:
+
+### ❌ WRONG: using `as` to bypass types
+
+```typescript
+// ❌ WRONG: Casting away type safety
+const context = {...} as any;
+const value = context.something as unknown as string;
+```
+
+### ✅ CORRECT: use proper types
+
+```typescript
+import type { Context } from '../types';
+
+// ✅ CORRECT: Rely on type inference
+const context: Context = {...};
+const value = context.something.MyField; // Properly typed
+```
+
+### In a test fixture, spread the generated defaults
+
+`as unknown as Context` in a test is usually a fixture that grew too big to write by hand: `Context` is the union of every capability the resource declares, and TypeScript requires all of them. Spread `defaultContext` from the generated `defaults.ts` beside the types and override only what the case is about:
+
+```typescript
+import { defaultContext } from './defaults';
+import type { Context } from './types';
+
+// ✅ CORRECT: complete, checked, and one line
+const context: Context = { ...defaultContext, inventory: { Stock: 100 } };
+```
+
+See [Testing](testing.md#starting-from-the-generated-defaults).
+
+## Rule 6: let generated types update automatically
+
+Never manually write `types.ts`. Always run `pnpm run generate` after capability or settings schema changes:
+
+```bash
+# After ANY variablesSchema or settingsSchema change:
+pnpm run generate
+
+# This regenerates types.ts with the latest schema
+```
+
+Manual `types.ts` files lead to:
+
+- Types being out of sync with schema
+- Missing fields
+- Runtime errors despite 'type checking'
+
+## Checklist for type safety
+
+Before creating a capability or settings resource:
+
+- [ ] Using proper JSON Schema types (number, string, boolean, object, array)?
+- [ ] Objects defined with `properties` and `required`?
+- [ ] Arrays defined with an `items` schema (a `default` alone types nothing)?
+- [ ] Nested objects closed with `"additionalProperties": false`?
+- [ ] No `any` types in engine code?
+- [ ] No string-based JSON parsing (use object type instead)?
+- [ ] Numeric constraints defined (min/max) in schema?
+- [ ] Generated types imported in engine logic?
+- [ ] Ran `pnpm run generate` after schema changes?
+- [ ] Engine functions use `RunFunction<Context, Settings>` signatures?
+
+## Common patterns
+
+### Settings numbers
+
+```bash
+pnpm run sdk new settings '{
+  "definition": {
+    "identifier": "targets",
+    "settingsSchema": {
+      "type": "object",
+      "properties": {
+        "DailySalesTarget": {
+          "type": "number",
+          "default": 100,
+          "minimum": 0,
+          "description": "Daily sales target in units"
+        },
+        "DiscountPercentage": {
+          "type": "number",
+          "default": 0.1,
+          "minimum": 0,
+          "maximum": 1,
+          "description": "Discount as decimal (0.1 = 10%)"
+        }
+      },
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+Every settings property declares a `default`, and a `settingsSchema` carries no top-level `required`: every property always has a value. A resource that lists `"settings": ["targets"]` reads `settings.targets.DailySalesTarget` as a `number`.
+
+### Complex objects
+
+```bash
+pnpm run sdk new capability '{
+  "definition": {
+    "identifier": "marketdata",
+    "variablesSchema": {
+      "type": "object",
+      "properties": {
+        "MarketConditions": {
+          "type": "object",
+          "properties": {
+            "demandLevel": { "type": "string" },
+            "competitorCount": { "type": "number", "minimum": 0 },
+            "growthRate": { "type": "number" },
+            "priceRange": {
+              "type": "object",
+              "properties": {
+                "min": { "type": "number", "minimum": 0 },
+                "max": { "type": "number", "minimum": 0 }
+              },
+              "required": ["min", "max"],
+              "additionalProperties": false
+            }
+          },
+          "required": ["demandLevel", "competitorCount", "growthRate", "priceRange"],
+          "additionalProperties": false,
+          "default": {
+            "demandLevel": "high",
+            "competitorCount": 5,
+            "growthRate": 0.05,
+            "priceRange": { "min": 50, "max": 200 }
+          },
+          "description": "Current market conditions"
+        }
+      },
+      "required": ["MarketConditions"],
+      "additionalProperties": false
+    }
+  }
+}'
+```
+
+The generated type will be precise:
+
+```typescript
+export interface Context {
+    marketdata: {
+        MarketConditions: {
+            demandLevel: string;
+            competitorCount: number;
+            growthRate: number;
+            priceRange: {
+                min: number;
+                max: number;
+            };
+        };
+    };
+}
+```
+
+## Why this matters
+
+Type safety in Serious Gaming:
+
+1. **Catches mistakes at build time** - not runtime
+2. **IDE assistance** - autocomplete, rename refactoring
+3. **Self-documenting code** - types are documentation
+4. **Prevents silent failures** - schema enforces constraints
+5. **Easier debugging** - stack traces point to real issues, not parsing errors
+
+When you skip proper typing, you:
+
+- Spend time debugging JSON parsing errors
+- Miss out on IDE help
+- Create ambiguous code that's hard to maintain
+- Introduce runtime errors from schema mismatches
+
+## See also
+
+- [Creating capabilities](./capabilities.md): defining capability schemas
+- [Creating engines](./engine.md): writing engine logic
+- [The state model](./capabilities.md#the-state-model): how context is scoped and updated