Research a simpler reactive-prop DX than the static-properties + declare pattern

[vivek7405]

Question

Can webjs offer a reactive-prop DX with NO declare line, where the types flow from the property declaration itself (the user writes the shape once and this.count is typed), while holding every webjs invariant: no build step, source-is-runtime (what you write is what ships to the browser), erasable TypeScript only, and no decorators?

The current pattern needs three pieces per prop: static properties = { count: { type: Number } }, a declare count: number, and a constructor default. The declare is the part that feels worst.

Answer: yes, it is feasible, via a typed base-class factory. Proven on all three axes.

The blocker is real but narrower than it looks. It only exists if you insist on keeping static properties as a STATIC FIELD: TypeScript cannot type a class's instance members from a value sitting in that class's own static field (no decorator-free mechanism, no chicken-and-egg resolution). So as long as the declaration lives in a static field, a separate declare is the only way to type the accessor.

Move the declaration into a base-class FACTORY call and the limitation disappears, because now the props are a function argument whose type the factory can map into the returned class's instance type:

class Counter extends Component({
  count: prop(Number, { reflect: true, default: 0 }),
  name:  prop(String, { default: 'xyz' }),
  student: prop(Student),
  tags:  prop<Tag[]>(Array, { default: () => [] }),     // explicit type for richer shapes
  mode:  prop<'light' | 'dark'>(String, { default: 'light' }),
}) {
  render() {
    return html`${this.count} ${this.name} ${this.student.name} ${this.mode}`;
    //            number       string       Student.name        union, all typed, NO declare
  }
}
Counter.register('counter-x');

prop(Number) infers number, prop(Student) infers Student from the constructor; a richer type than the constructor implies (a string[] array, a string union) is given once as prop<T>(Ctor). The base factory maps the shape { count: PropDef<number>, ... } to instance members { count: number, ... } via a mapped type, intersected with the WebComponent base, so this.count AND this.requestUpdate() are both visible.

Verified, not asserted

1. Types flow, no declare. A prototype type-checks under strict + erasableSyntaxOnly: this.count is number, this.student is Student, this.mode is the union; @ts-expect-error confirms a wrong-type assignment (this.count = 'x') is a real error. So the types genuinely flow, they are not any.
2. Source-is-runtime holds. Running the user-side source through module.stripTypeScriptTypes leaves valid runtime: the type args (<Tag[]>, <'light'|'dark'>) erase in place and extends Component({ ... prop(Array, { default: () => [] }) ... }) survives as the real runtime that ships and runs. Nothing is generated, nothing is rewritten. What you write IS what ships.
3. Runtime works against the real WebComponent, no framework rewrite. Component(shape) returns class extends WebComponent { static properties = shape }; the existing _initializeProperties reads Ctor.properties unchanged. An end-to-end run (linkedom) confirmed defaults seeding, reactivity, attribute reflection, and fresh-per-instance function defaults all work.

Why this beats the alternatives (all the dead-ends, with proof)

• @property() decorator (Lit's one-liner): non-erasable, would force a build step. Banned by invariant 10. Out.
• TC39 accessor keyword: a runtime syntax error on Node 26 / V8 without the decorators proposal (verified), and the stripper leaves it intact because it is not a type, so it crashes at load. Also does not register reactivity without a decorator. Out.
• prop() as a class FIELD (count = prop(Number)): a class-field initializer is clobbered after super() by [[Define]] semantics (verified: the own descriptor's getter becomes undefined), so it stores a box, not a reactive accessor. Out.
• Infer instance types from a static properties FIELD: impossible in TypeScript (the core blocker above). Out.
• A TS language-service plugin that synthesizes the declares virtually: works in-editor only; webjs typecheck (tsc on CLI/CI) still errors because a plugin does not affect tsc. Out unless paired with codegen.
• Codegen real .d.ts via webjs types: reintroduces a generate/watch step and a drift surface. Violates no-build. Out.

The factory is the one approach that clears every constraint at once.

Tradeoffs (why this is a design decision, not an obvious yes)

1. It diverges from Lit's static properties static-field shape. webjs is lit-shaped on purpose; extends Component({ ... }) is not a Lit idiom, and Lit muscle memory reaches for static properties + @property/declare. This is a real positioning cost.
2. Split declaration surface. Props move into the factory arg, but other static config (static shadow, static styles, static lazy) stays as static fields on the subclass, so a component reads as extends Component({props}) plus static shadow = true.
3. Broad tooling/docs migration. webjs check (the reactive-props-use-declare rule scans static properties), @webjsdev/intellisense, MCP list_components, the scaffold templates, the docs site, AGENTS.md, the lit-muscle-memory gotchas, and the four dogfood apps all assume the static-field model. Adopting the factory touches all of them.
4. Coexist vs replace. Shipping the factory ALONGSIDE the static-field model doubles the prop-declaration API surface (two ways to do the same thing). Replacing it is a clean single model but a full migration. webjs has no users yet (no backward-compat burden), so a clean replacement is genuinely on the table, but it is a significant call.

Recommendation

The declare-free DX is feasible and the win is real (one declaration, fully typed, no declare, no build, source-is-runtime). I recommend pursuing the typed base-class factory as the path, and deciding replace vs coexist as an explicit design choice (replacing is cleaner given zero users; coexisting is safer but heavier on the API surface). Implementation is separate tracked work.

The incremental default option (drop the constructor for the common case) is a strict prerequisite/complement either way: the factory examples above already rely on it, and it improves the existing static-field model on its own. It is implemented in PR #575.

[vivek7405]

Deep-dive: the prototypes that prove feasibility

Recording the exact spikes so the conclusion is reproducible.

1. Type prototype (tsc strict + erasableSyntaxOnly, PASS)

type PropConstructor<T> = (new (...a: any[]) => T) | ((v: any) => T);
interface PropDef<T> { reflect?: boolean; state?: boolean; default?: T | (() => T); readonly __t?: T }

// Map a runtime constructor to the type it implies (Number -> number, not the wrapper).
type Infer<C> =
  C extends BooleanConstructor ? boolean :
  C extends NumberConstructor ? number :
  C extends StringConstructor ? string :
  C extends new (...a: any[]) => infer T ? T :
  C extends (v: any) => infer T ? T : unknown;

declare function prop<C extends PropConstructor<any>>(type: C, opts?: PropDef<any>): PropDef<Infer<C>>;
declare function prop<T>(type: PropConstructor<any>, opts?: PropDef<T>): PropDef<T>;   // explicit override
declare function prop<T = string>(opts?: PropDef<T>): PropDef<T>;

type PropsOf<S> = { [K in keyof S]: S[K] extends PropDef<infer T> ? T : never };
declare function Component<S extends Record<string, PropDef<any>>>(shape: S): new () => WebComponentBase & PropsOf<S>;

The user-side class Counter extends Component({ count: prop(Number), student: prop(Student), tags: prop<Tag[]>(Array) }) { ... } type-checks with this.count: number, this.student: Student, this.tags: Tag[], and the two @ts-expect-error lines (assigning a string to count, an arbitrary string to a union mode) both fire. No declare anywhere.

2. Strip prototype (source-is-runtime, PASS)

module.stripTypeScriptTypes on the user-side source erases the type args in place and preserves the runtime verbatim:

tags: prop<Tag[]>(Array, { default: () => [] })
  ->  tags: prop       (Array, { default: () => [] })

The extends Component({ ... }) call and every prop(...) call survive untouched. Nothing generated, nothing rewritten.

3. Runtime prototype (real WebComponent, linkedom, PASS)

function prop(type, opts = {}) {
  if (type && typeof type === 'object' && !('call' in type)) { opts = type; type = undefined; }
  return { ...(type ? { type } : {}), ...opts };
}
function Component(shape) { return class extends WebComponent { static properties = shape; }; }

A Counter extends Component({ count: prop(Number, { reflect: true, default: 0 }), tags: prop(Array, { default: () => [] }) }) upgraded, seeded its defaults, reflected count to the attribute on change, re-rendered reactively, and gave each instance a fresh tags array. Zero changes to _initializeProperties (it already reads Ctor.properties).

Note on the user's literal-shape wish

The ideal static properties = { count: number, student: Student } (writing the TYPE names as the value) is not reachable, because number is a type and Student is a value, so the object would not strip to valid runtime and the static field could not type the instance anyway. { count: prop(Number), student: prop(Student) } inside the factory is the runnable near-equivalent, and it additionally carries reflect / state / default.

Cross-reference

The incremental default option (constructor-free common case) is in PR #575. The typed-factory implementation, and the replace-vs-coexist decision, are filed as separate implementation work.

[vivek7405]

Refinement: the bare-constructor factory is the sharpest form (closest to the original wish)

The factory does NOT need a prop() wrapper for the common case. It accepts the same bare-constructor shape you would have written in static properties, with values from the constructor and no declare:

class Counter extends Component({ count: Number, name: String, student: Student }) {
  constructor() {
    super();
    this.count = 0;                    // typed number
    this.name = 'xyz';                 // typed string
    this.student = new Student('ada'); // typed Student
  }
  render() { return html`${this.count} ${this.student.name}`; }
}

Verified under strict + erasableSyntaxOnly: this.count is number, this.student is Student, a wrong-type assign is a real error, and the source strips to that exact runtime. The prop(...) helper is only needed when a prop wants options (reflect, state, default) or a richer type than the constructor implies (prop<Tag[]>(Array)).

Why the declaration must move out of a static field (proven, not chosen)

The only delta from the literal static properties = { count: Number, ... } wish is that the shape lives in extends Component({...}). This is a hard TypeScript limitation, demonstrated with a minimal repro:

class Counter extends WebComponentBaseClass {
  static properties = { count: Number, name: String, student: Student };
  constructor() { super(); this.count = 0; }  // tsc: "Property 'count' does not exist on type 'Counter'"
}

A static field's value type cannot flow into the instance member types of the same class. There is no decorator-free, build-free mechanism to bridge it (a TS language-service plugin fixes the editor but not tsc on CI; codegen reintroduces a build step). Moving the identical object into the base-class factory call is the one move that lets the types reach this, with everything else (the value shape, the constructor-provided values, no declare) exactly as desired.

[vivek7405]

Finalized API: dual-role WebComponent, not a separate Component name

The factory is the SAME identifier as the base class. extends WebComponent({ count: Number, student: Student }) for typed props (no declare, values from constructor), and plain extends WebComponent unchanged. WebComponent becomes callable (returns a typed subclass) as well as constructable (via new.target + Reflect.construct), with a dual construct+call type signature. Verified on runtime and types (strict + erasableSyntaxOnly), source-is-runtime holds. Full mechanism recorded on the implementation issue #593.

[vivek7405]

Finalized DX Design

Following further evaluation, the finalized DX for declare-free reactive properties is the dual-role callable WebComponent base class, with default values defined cleanly in the constructor (avoiding redundant annotations or decorators):

class Counter extends WebComponent({
  count: Number
}) {
  constructor() {
    super();
    this.count = 0; // Fully typed (number), no declare!
  }

  render() {
    return html`<p>Count: ${this.count}</p>`;
  }
}
Counter.register('my-counter');

This represents the cleanest, most idiomatic TypeScript form that satisfies all core constraints:

• No declare line needed: Types flow dynamically to this.count from the WebComponent({ count: Number }) factory definition.
• Valid, uncompiled JS: The value-level Number acts as the standard JS coercion constructor, meaning no compilation/build overhead is introduced.
• Pure erasable TypeScript: Fully compatible with Node 24+ / Bun's type stripping out-of-the-box.

[vivek7405]

Resolved by merging #597