# Writing a kit with classes

> The shapes a reusable kit is written in — a generic base an app subclasses, a virtual `Defaults()` the subclass overrides, a `Test<V>(Func<T, V> field, …)` helper over a selector, a `Func` member with a default, and `f is TField` over the app's own types. Each answers what C# answers, on the server and in the browser alike.

<!-- id: class-kit-idioms · area: class · stability: preview · html: https://osysharp.com/reference/class/kit-idioms/ -->

## Summary        {#summary}
A kit hands the app a generic base; the app closes it over its own entity and overrides what it needs:

```osy title="a rule kit, and an app's rules written against it" test app=class-kit-idioms
enum Op { Is, IsNot }
enum Stage { New, Ready }
entity Job { Stage Stage = Stage.New; }

class Spec { public Op Op; public string Value = ""; }
class Default { public string Key = ""; public List<Spec> If = []; }

class SubjectBase { public virtual List<Default> Defaults() { return []; } }
class Subject<T> : SubjectBase {
  public Spec Test<V>(Func<T, V> field, Op op, V value) { return new Spec { Op = op, Value = $"{value}" }; }
  public Op Is => Op.Is;
}

class JobRules : Subject<Job> {
  public override List<Default> Defaults() {
    return [new Default { Key = "rush", If = [Test(j => j.Stage, Is, Stage.Ready)] }];
  }
}

string FirstRule() {
  var d = new JobRules().Defaults().First();
  return $"{d.Key}:{d.If.First().Op}:{d.If.First().Value}";   // "rush:Is:Ready"
}
```

`JobRules` inherits `Test<V>` from `Subject<T>`, with `T` bound to `Job`, so `j => j.Stage` is checked against
`Job` and `V` is inferred as `Stage`. Called from a page's action, the same code runs in the browser.

## Signature      {#signature}
```osy syntax
class Subject<T> : SubjectBase { public R Test<V>(Func<T, V> field, …, V value) { … } }   // a selector helper
class AppRules : Subject<AppEntity> { public override … Defaults() { … Test(x => x.Field, …) … } }
[AppSetting("Key")] class Setup { public Func<int, string> Format = n => $"{n} kr"; }  // a Func member with a default
class Holder<TField> where TField : BaseEntity { public bool Holds(BaseEntity f) => f is TField; }
```

## Description    {#description}

### An inherited method is the base's method   {#inherited}
A call to a method a base class declares runs the base's body, whatever class the call is written in. The same is
true of a generic base: `Test(…)` inside `JobRules` is `Subject<Job>.Test`. A page action that builds
`new JobRules().Defaults()` evaluates the call in the browser, just as a server function does.

### A `Func` member's default is a function   {#func-default}
A `Func<…>` field may have an initializer, as in C#. The lambda is typed by the field, so its parameters need no
types of their own, and every new instance starts with it:

```osy title="a formatting function as a setting's default" test app=class-kit-idioms-func
[AppSetting("Fmt")]
public class FmtSetup {
  public Func<int, string> Price = n => $"{n} kr";
  public int Tax = 25;
}

string Shown() {
  // The app has never set Fmt: the setting answers its declared defaults, the Func member included.
  return App.Setting<FmtSetup>().Price(5);       // "5 kr"
}
```

This works the same way on a plain class (`new Plain().Price(5)`). An initializer can be a lambda or any other
expression of the field's type. The interpolated string inside it keeps its formats and conditionals
(`$"{n:D3} {(n > 1 ? "items" : "item")}"`).

### `f is TField` over the app's own types   {#is-typeparam}
A kit that is generic over "which kind of row" tests a value against its type parameter. `TField` is whatever the
app bound it to, and the test reads the value's real type — for an entity, the type the row was created as:

```osy title="a holder that recognises one subtype" test app=class-kit-idioms-is
entity Field { [MaxLength(60)] string Name = ""; }
entity GuestField : Field { }
entity RoomField : Field { }

class Holder<TField> where TField : Field {
  public bool Holds(Field f) => f is TField;
}

bool Recognises() {
  var holder = new Holder<GuestField>();
  return holder.Holds(new GuestField()) && !holder.Holds(new RoomField());   // true
}
```

A row made on the page and not yet saved already has its type. `new GuestField()` in an action is a `GuestField`
before the commit, in the browser as on the server.

## Examples       {#examples}

```osy title="an app's rules over an entity subject, read from a page" test app=class-kit-idioms-page
enum Stage { New, Ready }
entity Job { Stage Stage = Stage.New; security { allow read when IsAnonymous || IsAuthenticated; } }

class Subject<T> {
  public string Test<V>(Func<T, V> field, V value) { return $"{value}"; }
}
class JobRules : Subject<Job> {
  public string Ready() { return Test(j => j.Stage, Stage.Ready); }
}

[Route("/rules")] [AllowAnonymous]
component RulesPage() {
  string shown = "";
  action Go() { shown = new JobRules().Ready(); }     // runs in the browser: "Ready"
  render { Text(shown); Button("go", onPress: Go); }
}
```

## Errors         {#errors}

| Message | Cause | Fix |
|---|---|---|
| `cannot infer 'V'` | Neither an argument nor the selector's body says what `V` is. | Pass a value of the field's type, or write the type: `Test<Stage>(j => j.Stage, …)`. |
| `a lambda needs a target type to bind its parameter from` | A lambda was written where nothing declares its type — a `var`, or a member typed `object`. | Declare the member as the `Func<…>` it holds. |
| `'X' and 'Y' are not in the same hierarchy, so no row can be both` | `f is TField` where the constraint's base and `f`'s type are unrelated. | Constrain `TField` to the base `f` is declared as (`where TField : Field`). |

## See also       {#see-also}
- [Generic classes](https://osysharp.com/reference/class/generics/) — type parameters, constraints and how a subclass closes a generic base
- [Class inheritance](https://osysharp.com/reference/class/inheritance/) — `virtual`, `override`, and which body runs
- [Testing which class a value is](https://osysharp.com/reference/class/type-tests/) — `is` and `as` on classes and entities
- [App.Implementations<T>()](https://osysharp.com/reference/class/app-implementations/) — finding the app's implementations of a kit's contract
- [class properties](https://osysharp.com/reference/class/properties/) — fields, initializers and their defaults
