Decorators

[stazz]

It would be great to have something like this:

// app.ts
import * as tyras from "@ty-ras/...";
export default tyras.createAppBuilder<...>();

// my-endpoint.ts
import * as tyras from "@ty-ras/...";
import app from "./app";


class Endpoints {
  @staticURL.endpoint({ state: "" })
  public doSomething({ state }) {
    // The type of the 'state' would be automatically deduced here!
  }
}

// Notice that we must create the `staticURL` _after_  class declaration.
// This still gives us only duck type -safety, but at least it is something
export const staticURL= app.endpointsFor(Endpoints, { url: "/hello" }); // We must use separate instance in order to make it even possible to infer types for methods, even after TS issue is solved! Can not use `app` itself directly to decorate different methods of different classes.

// main.ts
import app from "./app";
import myEndpoint from "./my-endpoint";

// Will be of type Array<tyras.AppEndpoint<TContext, TStateInfo>>.
export default app.materializeEndpoints(
  "/api/v1": [ myEndpoint ],
  ...
);

However, this will not work until this TS issue has been solved: microsoft/TypeScript#4881 . Perhaps its chances of survival are now marginally better, after TS 5 introduced non-experimental support for decorators.

As such, using decorators within TyRAS does not make sense at all until the TS issue is solved (?).

Specifying types of arguments explicitly is something I am not sure will be much difference from the current way of using builders and such. However, it is maybe worth exploring after 1.0.0 is out.

[stazz]

On TyRAS side it would look something like this:

import * as builders from ".";
import type * as dataBE from "@ty-ras/data-backend";
import type * as data from "@ty-ras/data";

const createAppBuilder = <TStringDecoder>(): AppBuilder<TStringDecoder> => {
  const builder0 = builders.startBuildingAPI();
  const endpointsFor: AppEndpointSpecifierFactory<TStringDecoder> = (<
    TURLData extends dataBE.RuntimeAnyURLData,
  >({
    url,
  }:
    | AppEndpointSpecifierFactoryArgsStaticURL
    | AppEndpointSpecifierFactoryArgsURLParameters<
        TStringDecoder,
        TURLData
      >) => {
    const specifier:
      | AppEndpointSpecifier
      | AppEndpointSpecifierWithURL<TURLData> = {
      endpoint() {
        return (method: ClassMethodForEndpoint<any, any, any>, context) => {};
      },
    };
    return specifier;
  }) as any;
  return {
    endpointsFor,
  };
};

interface AppBuilder<TStringDecoder> {
  endpointsFor: AppEndpointSpecifierFactory<TStringDecoder>;
}

interface AppEndpointSpecifierFactory<TStringDecoder> {
  (args: AppEndpointSpecifierFactoryArgsStaticURL): AppEndpointSpecifier;
  <TURLData extends dataBE.RuntimeAnyURLData>(
    args: AppEndpointSpecifierFactoryArgsURLParameters<
      TStringDecoder,
      TURLData
    >,
  ): AppEndpointSpecifierWithURL<builders.EndpointHandlerArgsWithURL<TURLData>>;
}

interface AppEndpointSpecifierFactoryArgsStaticURL {
  url: string;
  // metadata: ...
}

interface AppEndpointSpecifierFactoryArgsURLParameters<
  TStringDecoder,
  TURLData extends dataBE.RuntimeAnyURLData,
> {
  url: {
    args: ReadonlyArray<string>;
    spec: dataBE.URLParameterValidatorSpec<TURLData, TStringDecoder>;
  };
  // metadata: ...
}

interface AppEndpointSpecifier {
  endpoint(args: {
    state: string;
  }): <This, Return>(
    method: ClassMethodForEndpoint<{}, This, Return>,
    context: ClassMethodDecoratorContext,
  ) => void;
}

// eslint-disable-next-line @typescript-eslint/no-empty-interface
interface AppEndpointSpecifierWithURL<TURLData extends object> {
  endpoint(args: {
    state: string;
  }): <This, Return>(
    method: ClassMethodForEndpoint<{ url: TURLData }, This, Return>,
    context: ClassMethodDecoratorContext,
  ) => void;
}

type ClassMethodForEndpoint<TArgs extends Record<string, any>, This, Return> = (
  this: This,
  args: { state: string } & TArgs,
) => Return;

[stazz]

Some notes

function endpointsFor<TClass>(
    theClass: new () => TClass,
  ): ((
    args: {...},
  ) => <Args extends Array<any>, Return>(
    method: (this: TClass, ...args: Args) => Return,
    ctx: ClassMethodDecoratorContext<TClass, typeof method>,
  ) => void) =>
  (args) =>
  (method, ctx) => {
    // Use 'theClass' and "===" comparison against 'this' to find correct builder and modify it.
  };

[stazz]

This is now implemented with #93 .