typespec-typescript-emitter 1.2.0 → 2.0.1

package/README.md

@@ -1,29 +1,32 @@
-# typespec-typescript-emitter
+# typespec-typescript-emitter <!-- omit from toc -->
 
-This is a [TypeSpec](https://typespec.io) library aiming to provide TypeScript output to a TypeSpec project.
+This is a [TypeSpec](https://typespec.io) library aiming to provide TypeScript (*TS*) output to a TypeSpec (*TSP*) project.
 
-Currently, this library is tailored to my specific use case, which is defining HTTP APIs.
-The 'routes'-emitter will only work on HTTP operations. **However**, exporting all models as types is independent of HTTP, and so may also benefit projects with a different usage scenario.
+While this library is tailored to HTTP APIs, it can certainly be useful to other types of projects.
 
 It can the following things:
 
-- ts files exporting every model present in a namespace
-  - 1 file for each nested namespace
-  - exports models, enums and unions
-  - does NOT export aliases (see below)
-- optional typeguards, *if* type export is enabled
-- for `TypeSpec.Http`: ts file containing a nested object (by namespace-opname) containing information about every route (eg. url-from-parameters, method, etc.)
-- for `TypeSpec.Http`: "routed typemap" mapping types to their routes (path and verb) (respects Lifecycle visibility)
+- export TypeScript files containing each enum, scalar, model and union present in your TSP files
+- generate narrow typeguards for all emitted types
+- *for HTTP*: export a nested object containing information about every route (eg. url-from-parameters, method, etc.)
+- *for HTTP*: export a "routed typemap", making expected request and response body types accessible using the operation's path
 
 ## Content <!-- omit from toc -->
 
-- [typespec-typescript-emitter](#typespec-typescript-emitter)
-  - [Installation](#installation)
-  - [Configuration](#configuration)
-  - [Types Emitter](#types-emitter)
-    - [Aliases](#aliases)
-  - [Routes Emitter](#routes-emitter)
-  - [Routed Typemap](#routed-typemap)
+- [Installation](#installation)
+- [Configuration](#configuration)
+- [Emitter: Types](#emitter-types)
+  - [Types](#types)
+  - [Typeguards](#typeguards)
+  - [Lifecycle Visibility](#lifecycle-visibility)
+    - [In Types](#in-types)
+    - [In Typeguards](#in-typeguards)
+  - [Nominal Enums](#nominal-enums)
+- [Emitter: Routes](#emitter-routes)
+- [Emitter: Routed Typemap](#emitter-routed-typemap)
+- [Contributing](#contributing)
+  - [Short Overview](#short-overview)
+  - [Todo](#todo)
 
 ## Installation
 
@@ -40,7 +43,9 @@ emit:
   - "typespec-typescript-emitter"
 options:
   "typespec-typescript-emitter":
-    root-namespace: "string"
+    root-namespaces:
+      - "namespace1"
+      - "namespace2"
     out-dir: "{cwd}/path"
     enable-types: true
     enable-typeguards: false
@@ -52,271 +57,369 @@ options:
 
 The following options are available:
 
-- `root-namespace` **(required)**: name of the most outer namespace. As the TypeSpec docs recommend, your project is expected to consist of one or more nested namespaces. Here, you need to specify the most outer / general namespace you want emitted.
-- `out-dir`: output directory. Must be an absolute path; replacers like `{cwd}` are permitted.
+- `root-namespaces` **(required)**: array of names of all namespaces in your program you want to emit from. You don't need to specify namespaces nested inside other namespaces, as the ones listed will be traversed recursively.
+- `out-dir` **(required)**: output directory. Must be an absolute path; replacers like `{cwd}` are permitted.
 - `enable-types` (default: true): enables output of TypeScript types.
-- `enable-typeguards` (default: false): enables output of typeguards, *IF* type-output is enabled.
-- `enable-routes` (default: false): enables output of the HTTP-routes object.
-- `enable-routed-typemap` (default: false): enables output of an indexable type mapping paths and HTTP verbs to request and response bodies.
-- `string-nominal-enums` (default: false): outputs member names as strings instead of index values for enum members declared without explicit values (routed typemap only, see [example](#routed-typemap)).
-- `serializable-date-types` (default: false): outputs serializable types for typespec's dates types that match OpenApi spec. Types like `offsetDateTime`, `plainDate` and `utcDateTime` will be emitted as `string` and `unixTimestamp32` as `number`.
+- `enable-typeguards` (default: false, **requires** `enable-types`): enables output of [typeguards](#typeguards).
+- `enable-routes` (default: false): enables output of the [HTTP-routes object](#emitter-routes).
+- `enable-routed-typemap` (default: false, **requires** `enable-types`): enables output of an [indexable type](#emitter-routed-typemap), mapping paths and HTTP verbs to request and response bodies.
+- `string-nominal-enums` (default: false): outputs member names as strings instead of index values for enum members declared without explicit values.
+- `serializable-date-types` (default: false): outputs serializable types for typespec's dates types that match OpenApi spec. Types like `offsetDateTime`, `plainDate` and `utcDateTime` will be emitted as `string` and `unixTimestamp32` as `number`. If disabled, all these types resolve to `Date`.
 
-## Types Emitter
+## Emitter: Types
 
-This emitter will traverse your configured root namespace and all nested namespaces, generating a `{namespace-name}.ts`-file.
+All examples in this section use this input:
 
-The emitter can handle `Model`s, `Enum`s and `Union`s. ~~`Alias`'s~~ are *not* emitted - more on that [later](#aliases). It will also preserve docs as JSDoc-style comments.
+```ts
+namespace Showcase {
+  enum Status {
+    Status1,
+    Status2
+  }
 
-The emitter should be able to handle most basic TS contructs, like scalars, literals, object, arrays, tuples and intrinsics (eg. `null`).
+  /** A showcase model. */
+  model Mdl {
+    status: Status,
+    something: string,
+    someNumber: int32,
+    nestedModel: {
+      name: string
+    }
+  }
 
-> [!IMPORTANT]
-> These types do not respect most transformative decorators, notable `@visibility`.
-> This is because it's non-trivial to do, has unexpected problems and the functionality is *somewhat* already there, in the form of [Routed Typemaps](#routed-typemap).
-> For additional information, see [#7](https://github.com/crowbait/typespec-typescript-emitter/issues/7).
+  @get
+  op getModel(): {@statusCode status: 200, @body body: Mdl};
+
+  @route("/inner")
+  namespace InnerNamespace {
+    scalar ID extends uint32;
+    scalar Name extends string;
+
+    model InnerNamespaceModel {
+      @visibility(Lifecycle.Read)
+      id: ID,
+      name: Name,
+      @visibility(Lifecycle.Create)
+      created?: unixTimestamp32,
+      parent: Mdl
+    }
 
-Example:
+    @post
+    op create(@body body: InnerNamespaceModel): OkResponse;
 
-```ts
-namespace myProject { // remember to set in config!
-  enum ReadStatus {
-    Never,
-    Once,
-    Often
-  }
-  union Author {"unknown" | string}
-  model Book {
-    author: Author,
-    title: string,
-    subtitle: null | string,
-    read: ReadStatus,
-    chapterTitles?: string[]
+    @delete
+    @route("{id}")
+    op del(@path id: ID): {@statusCode status: 200, @body body: InnerNamespaceModel} | UnauthorizedResponse;
   }
-
-  // you can either nest namespaces like this:
-  namespace subNameSpace {/* ... */}
-  // ... or specify them in (and import from) external files:
-  namespace myProject.subNameSpace {/* ... */} // this is in another file
-  // The emitted file will always have the name of the namespace it's
-  // *currently* investigating, in this case:
-  // `SubNameSpace.ts`
 }
 ```
 
-...will be transformed into:
+Naturally, you can also split your declarations into multiple files and import them.
+
+### Types
 
 ```ts
-/* /path/to/outdir/MyProject.ts */
-export enum ReadStatus {
-  Never,
-  Once,
-  Often
-}
-export type Author = "unknown" | string;
-export interface Book {
-  author: Author,
-  title: string,
-  subtitile: null | string,
-  read: ReadStatus,
-  chapterTitles?: string[]
+// Showcase.ts
+
+export enum Status {
+  Status1,
+  Status2
 }
 
-// if `enable-typeguards` is set to true
-export function isBook(arg: any): arg is Book {
-  return (
-    (arg['author'] !== undefined) &&
-    (arg['title'] !== undefined && typeof arg['title'] === 'string') &&
-    (arg['subtitle'] !== undefined) &&
-    (arg['read'] !== undefined) &&
-    (arg['chapterTitles'] === undefined ||  Array.isArray(arg['chapterTitles']))
-  );
-};
+/** A showcase model. */
+export type Mdl = {
+  status: Status,
+  something: string,
+  someNumber: number,
+  nestedModel: {
+    name: string
+  }
+}
+```
 
-// the other namespace will be emitted to `/path/to/outdir/SubNameSpace.ts`
+```ts
+// Showcase.InnerNamespace.ts
+
+export type ID = number
+export type Name = string
+export type InnerNamespaceModel<V extends Lifecycle = Lifecycle.All> = FilterLifecycle<{
+  id: ID,
+  name: Name,
+  created?: Date,
+  parent: Showcase.Mdl
+}, {
+  'id': {vis: [Lifecycle.Read]},
+  'created': {vis: [Lifecycle.Create]}
+}, V>
 ```
 
-Typeguards *should* create comprehensive checks that adhere as strictly to the source model as possible.
-If you find a case where the typeguard is looser than it needs to be, please report that as a bug.
+As you can see, the output is split into files per namespace.
+The defined scalars are exported as types, as are the models, while enums are exported as-is (also see [nominal enums](#nominal-enums)).
+You can also see how the already-known `Mdl` is referenced by name.
 
-### Aliases
+If you're wondering why `InnerNamespaceModel` looks funny, check out the [lifecycle visibility](#lifecycle-visibility) section.
 
-There seems to be no way to extract aliases from TypeSpec's emitter framework. Because of that, `Alias`es are ignored by the emitter (or, to be more precise: `Alias`es reach the emitter already resolved. They won't be exported as their own type but directly substituted where they're needed).
+### Typeguards
 
-That means, if you want something to be emitted, it can't be an alias:
+Setting the option `enable-typeguards` to `true` will generate typeguards for all exported types.
+This is the output of our example:
 
 ```ts
-model Demo {
-  prop1: string,
-  prop2: int32
+// Showcase.ts
+
+export type Mdl = {
+  status: Status,
+  something: string,
+  someNumber: number,
+  nestedModel: {
+    name: string
+  }
 }
+export function isMdl(t: any): t is Mdl {return (
+  t['status'] !== undefined && (true) &&
+  t['something'] !== undefined && (typeof t['something'] === 'string') &&
+  t['someNumber'] !== undefined && (typeof t['someNumber'] === 'number') &&
+  t['nestedModel'] !== undefined && (
+    t['nestedModel']['name'] !== undefined && (typeof t['nestedModel']['name'] === 'string')    
+  )  
+)}
+```
+
+```ts
+export type ID = number
+export function isID(t: any): t is ID {return (typeof t === 'number')}
+
+export type Name = string
+export function isName(t: any): t is Name {return (typeof t === 'string')}
+
+export type InnerNamespaceModel<V extends Lifecycle = Lifecycle.All> = FilterLifecycle<{
+  id: ID,
+  name: Name,
+  created?: Date,
+  parent: Showcase.Mdl
+}, {
+  'id': {vis: [Lifecycle.Read]},
+  'created': {vis: [Lifecycle.Create]}
+}, V>
+export function isInnerNamespaceModel(t: any, vis: Lifecycle = Lifecycle.All): t is InnerNamespaceModel<typeof vis> {return (
+  ((vis as any) !== Lifecycle.All && ![Lifecycle.Read].includes(vis) ? !('id' in t) : (t['id'] !== undefined && (isID(t['id'])))) &&
+  t['name'] !== undefined && (isName(t['name'])) &&
+  ((vis as any) !== Lifecycle.All && ![Lifecycle.Create].includes(vis) ? !('created' in t) : (t['created'] === undefined || (t['created'] instanceof Date))) &&
+  t['parent'] !== undefined && (Showcase.isMdl(t['parent']))  
+)}
+```
+
+Typeguards are functions you can call to ensure some variable is exactly of the type you'd expect.
+As you can see, already-known typeguards are resused (similar to types). [Lifecycle visibility](#lifecycle-visibility) is respected.
+Typeguards are designed to be as restrictive as possible (except extra properties, those are not checked for). If you encounter one that is not as strict as it could be, please open an issue.
+
+### Lifecycle Visibility
 
-// will not be emitted:
-alias Derived1 = OmitProperties<Demo, "prop1">;
+As you have probably notices, some parts of our example have more complex output than others:
 
-// will be emitted:
-model Derived2 {...OmitProperties<Demo, "prop1">};
+```ts
+export type InnerNamespaceModel<V extends Lifecycle = Lifecycle.All> = FilterLifecycle<{
+  id: ID,
+  name: Name,
+  created?: Date,
+  parent: Showcase.Mdl
+}, {
+  'id': {vis: [Lifecycle.Read]},
+  'created': {vis: [Lifecycle.Create]}
+}, V>
+
+function isInnerNamespaceModel(t: any, vis: Lifecycle = Lifecycle.All) { /* ... */ }
 ```
 
-## Routes Emitter
+This is the Lifecycle system. In TypeSpec, you can use [lifecycle visibility](https://typespec.io/docs/language-basics/visibility/#lifecycle-visibility) to specify which parts of a model are present during creation of a resource, reading it, updating it, et cetera.
 
-**This emitter depends on your use of the `TypeSpec.Http` library**.
+This emitter allows you to work with that.
 
-If you're using `TypeSpec.Http` to define your API routes and endpoints, this library offers an emitter to export a `routes` object.
-It will generate a nested object containing information about every `op` you have defined, nested by namespace.
-I contains the following data (per `op`):
+Any type that has `@visibility` decorators *somewhere* will be "lifecycle-enabled". "Somewhere" does include nested types and extended types as well, so everything that is reference by the current type in any way.
+Working with lifecycles involves use of the `Lifecycle` enum, conveniently emitted alongside your regular project output.
 
-- `method`: HTTP method
-- `path`: Path (as defined in the `route` string; parameters are not substituted)
-- `getUrl`: Function for generating a valid URL to this `op`; if the path has parameters, this function will have matching parameters
-- `auth`: Array of valid authentication schemes (or `[null]`, if none)
-Just as the types emitter, this emitter will also preserve docs as JSDoc-style comments.
+#### In Types
 
-Example:
+Any type that is lifecycle-enabled gets a type parameter:
 
 ```ts
-@server("https://api.example.com", "Server")
-namespace myProject { // remember to set in config!
-  @get
-  op getSomething(): {@body body: string};
-  // if you want to use `typeguards-in-routes`, make sure
-  // to properly declare responses as a model with a `body`-property
+type T<V extends Lifecycle = Lifecycle.All>
+```
 
-  @get
-  @route("{param}")
-  @useAuth(NoAuth | BasicAuth)
-  op getSmthElse(@path param: string): {@body body: string};
+This parameter defaults to `All` (so you don't *have* to specify it), including all properties. If you access the type with `T<Lifecycle.Read>`, for example, all properties not visible on read will be excluded. This follows the normal TypeSpec behavior of *always* including all properties that do not have *any* visibility specified.
 
-  @route("/subroute")
-  namespace sub {
-    @post
-    @route("post/{post_param}")
-    @useAuth(BearerAuth)
-    op postSomething(
-      @path post_param: int32,
-      @body body: string
-    ): {@body body: string};
-  }
-}
+#### In Typeguards
+
+Let's look at the typeguard signature of a lifecycle-enabled type:
+
+```ts
+isInnerNamespaceModel(t: any, vis: Lifecycle = Lifecycle.All)
 ```
 
-...will be transformed into:
+Again, the lifecycle defaults to `All` and works similar to the type parameter. Also similarly, any typeguard that calls another typeguard which *has* lifecycle visibility, will also have it.
+
+### Nominal Enums
+
+In TypeSpec (and TypeScript), enums can be declared "plain" or with values:
 
 ```ts
-/* /path/to/outdir/routes_{root-namespace}.ts */
-export const routes_myProject = {
-  getSomething: {
-    method: 'GET',
-    path: '/',
-    getUrl: (): string => `/`,
-    auth: [null]
-  },
-  getSmthElse: {
-    method: 'GET',
-    path: '/{param}',
-    getUrl: (params: {param: string}): string => `/${params.param}`,
-    auth: [null, "BASIC"]
-  },
-  sub: {
-    postSomething: {
-      method: 'POST',
-      path: '/post/{post_param}',
-      getUrl: (params: {post_param: string}): string => `/post/${params.post_param}`,
-      auth: ["BEARER"]
-    }
-  }
-} as const;
+export enum Status {
+  STATUS_1,
+  STATUS_2
+}
+
+export enum StatusShifted {
+  STATUS_1 = 1,
+  STATUS_2 = 2
+}
+
+export enum StatusText {
+  STATUS_1 = 'Status 1',
+  STATUS_2 = 'Status 2'
+}
 ```
 
-## Routed Typemap
+The latter 2 will be emitted just as they are defined here, but the first example (the plain one) can be configured.
+By default, it is emitted as-is, but that may be undesirable. The `string-nominal-enums` config option emits enums without explicitely declared values in a way that uses the enum member names as their values:
 
-This emitter produces a Typemap (a typescript type indexed by string keys mapping other types) based on your HTTP routes and verbs.
-In short, this allows you to select a type *used in a body of your HTTP ops* using it's path and verb. This includes request and response bodies. Path parameters are not relevant for this emitter; those are already handled in the Routes object.
-This can be helpful when, for example, building a wrapper around your API.
+```ts
+export enum Status {
+  STATUS_1 = 'STATUS_1',
+  STATUS_2 = 'STATUS_2'
+}
+```
 
-> [!NOTE]
-> The Typemap is not nested! This means that, let's say the route "/user/account" will not be mapped to `{user: {account: /* ... */}}` (somewhat similar to how the Routes Emitter works), but to `{"/user/account": /* ... */}`. Crucially, those map keys are *the same as the `path` property in the Routes object* emitted from the Routes Emitter.
-> This means you can select from the Typemap *using* the structured Routes object.
+## Emitter: Routes
 
-Example:
+When enabled, this emitter will traverse your program to find all operations (`op`).
+These are then compiled into a single, nested object:
 
 ```ts
-@route("/typemap")
-namespace namespaceA.typemap {
-  enum State {
-    ACTIVE,
-    INACTIVE
-  }
-  enum Condition {
-    NEW = 'new',
-    USED = 'used'
+namespace Showcase {
+  enum Status {
+    Status1,
+    Status2
   }
 
-  model ModelA {
-    id: int32,
-    name: string,
-    state: State,
-    cond: Condition
+  /** A showcase model. */
+  model Mdl {
+    status: Status,
+    something: string,
+    someNumber: int32,
+    nestedModel: {
+      name: string
+    }
   }
 
   @get
-  op getAll(): {@body body: ModelA[]} | {@statusCode status: 418, @body body: "Me teapot"};
+  op getModel(): {@statusCode status: 200, @body body: Mdl};
+
+  @route("/inner")
+  namespace InnerNamespace {
+    scalar ID extends uint32;
+    scalar Name extends string;
+
+    model InnerNamespaceModel {
+      @visibility(Lifecycle.Read)
+      id: ID,
+      name: Name,
+      @visibility(Lifecycle.Create)
+      created?: unixTimestamp32,
+      parent: Mdl
+    }
 
-  @post
-  op add(@body body: ModelA): OkResponse;
+    @post
+    op create(@body body: InnerNamespaceModel): OkResponse;
 
-  @post
-  @route("{id}")
-  op getOne(
-    @path id: int32
-  ): {@body body: ModelA}| NotFoundResponse | {@statusCode status: 418} | {@statusCode status: 419, @body body: null};
+    @delete
+    @route("{id}")
+    op del(@path id: ID): {@statusCode status: 200, @body body: InnerNamespaceModel} | UnauthorizedResponse;
+  }
 }
 ```
 
-...will be transformed into:
+... will be transformed into:
+
+```ts
+export const routes_Showcase = {
+  getModel: {
+    verb: 'GET',
+    path: '/',
+    getUrl: (): string => `/`,
+    auth: [null]
+  },
+  InnerNamespace: {
+    create: {
+      verb: 'POST',
+      path: '/inner',
+      getUrl: (): string => `/inner`,
+      auth: [null]
+    },
+    del: {
+      verb: 'DELETE',
+      path: '/inner/{id}',
+      getUrl: (params: {id: string}): string => `/inner/${params.id}`,
+      auth: [null]
+    }
+  }
+} as const;
+```
+
+The main use cases are:
+
+- accessing URLs safely
+- using the `path` property to access the [typemap](#emitter-routed-typemap)
+
+## Emitter: Routed Typemap
+
+When enabled, this emitter provides a single indexed type from which the request and response body types can be accessed (same input as [above](#emitter-routes)):
 
 ```ts
-/* /path/to/outdir/routedTypemap_{root-namespace}.ts */
-export type types_namespaceA = {
-  ['/typemap']: {
+export type types_Showcase<V extends Lifecycle = Lifecycle.All> = {
+  ['/']: {
     ['GET']: {
       request: null
-      response: {status: 200, body: {
-        id: number,
-        name: string,
-        state: 0 | 1, // this would be `'ACTIVE' | 'INACTIVE'` with `string-nominal-enums: true`
-        cond: 'new' | 'used'
-      }[]} | {status: 418, body: 'Me teapot'}
-    },
+      response: {status: 200, body: Showcase.Mdl}
+    }
+  },
+  ['/inner']: {
     ['POST']: {
-      request: {
-        id: number,
-        name: string,
-        state: 0 | 1, // this would be `'ACTIVE' | 'INACTIVE'` with `string-nominal-enums: true`
-        cond: 'new' | 'used'
-      }
+      request: Showcase_InnerNamespace.InnerNamespaceModel<V extends Lifecycle.All ? (Lifecycle.Create) : V>
       response: {status: 200, body: {
-        /** The status code. */
         statusCode: 200
       }}
     }
   },
-  ['/typemap/{id}']: {
-    ['POST']: {
+  ['/inner/{id}']: {
+    ['DELETE']: {
       request: null
-      response: {status: 200, body: {
-        id: number,
-        name: string
-      }} | {status: 404, body: {
-        /** The status code. */
-        statusCode: 404
-      }} | {status: 418, body: {
-        status: 418
-      }} | {status: 419, body: null}
+      response: {status: 200, body: Showcase_InnerNamespace.InnerNamespaceModel<V extends Lifecycle.All ? (Lifecycle.Read) : V>} | {status: 401, body: {
+        statusCode: 401
+      }}
     }
   }
 };
 ```
 
-...which can be accessed like this:
+> [!TIP]
+> This type is not nested.
+> Each route can be accessed by using the `path` property on the corresponding entry in the `routes` object.
+
+This automatically applies [lifecycle visibilities](#lifecycle-visibility), where applicable. The assignment which HTTP verb leads to which visibility variant follows the logic TypeSpec uses internally:
+
+| Verb     | Lifecycles         |
+| -------- | ------------------ |
+| `HEAD`   | `Query`            |
+| `GET`    | `Query`            |
+| `POST`   | `Create`           |
+| `PUT`    | `Create \| Update` |
+| `PATCH`  | `Update`           |
+| `DELETE` | `Delete`           |
+| Return   | `Read`             |
+
+"Return" refers to *all* operation return types.
+
+The typemap itself has a lifecycle visibility parameter. If you access the typemap using any type parameter (except `Lifecycle.All`, which is the default), the returned type will be forced to the visibility you specified, overriding the HTTP-verb-specific selection.
 
 ```ts
 // Accessing type of response body directly by knowing path and verb
@@ -325,16 +428,56 @@ type T_update1 = types_namespaceA['/typemap']['POST']['response']['body']
 // Accessing type of request body by indexing Routes object
 // namespace "namespaceA.typemap", op "add"
 type T_update2 = types_namespaceA[typeof routes_namespaceA.typemap.add.path]['POST']['request']
-// One could also use `typeof routes_namespace.testSimple.update.method` instead of 'POST'.
+// You could also use `typeof routes_namespace.testSimple.update.method` instead of 'POST'.
 ```
 
-> [!NOTE]
-> Observe how the emitter
->
-> - assumes a `200` status code for an op's response type if you didn't define any (first responses on `getAll` and `getOne` ops)
-> - assumes the entire response type is the body of no body is explicitely decorated (418 on `getOne` op) (this is non-standard; I have seen quite a few projects not realizing the response definition should have a body *in* it and treating the whole thing as a body; so while technically "wrong", this accomodates those projects. You can easily define a truly empty body using `{}`, `""`, `null`..., see 419 on `getOne` op)
+## Contributing
+
+Thank you very much for considering investing time into this project!
+
+For the smoothest contributing experience, please consider these guidelines:
+
+- please use [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/#summary)
+- if your contribution expands functionality, please consider drafting tests for it
+
+You may find the following section helpful.
+
+### Short Overview
+
+This section roughly outlines the inner workings of the library.
+
+- `lib.ts` defines primarily emitter options
+- `emitter.ts` is the main entry point
+
+`$onEmit` calls the actual emitters defined in `emit_*` files.
+These each traverse the program, recursively collecting the objects they are interested in (emittable types, operations, ...) from the root namespaces specified by the user.
+
+The primary resolution of types and typeguards starts in `resolve/Resolvable.ts`.
+It defines an abstract class which both contains static functions to resolve types as well as inherited methods each type resolver implements and uses to recursively resolve.
+Each resolvable type defines its methods in an inherited class, in `resolve/types/[type].ts`.
+
+The primary flow of type resolution is quite simple:
+
+- `static Resolvable.resolve` calls `static Resolvable.for`, which returns a `Resolvable` instance for the specific type (we will call this instance `rt`, for "resolvable type")
+- `rt.resolve` first checks a list of all types found in the program - even if they have not been yet resolved, they will be and then will be emitted - so they should just be referenced. This returns the name and skips all further resolution, ending the process here.
+- `rt.type` or `rt.typeguard` are invoked: these are defined for each type in its class. Depending on the type, these either resolve directly, ending the process here, or have other types "within" them (unions or models, for example, have this). In this case, `rt.resolveNested` is called, which finishes the recursive loop by calling `static Resolvable.resolve` on the "child" type.
+
+Most of these methods do not return data, because they mutate an "output" object passed as a parameter. This has proven to be much more concise than passing return values up and down the chain.
+Also to be considered is the `hasVisibility` flag showing up at many points. This is used to ultimately determine whether a type needs lifecycle visibility handling in any way (because if any part of it does, so does the whole thing).
+
+### Todo
 
-Additional notes:
+There are some things left to do, most of which I hoped to get ready for 2.0.0, however, that didn't work out.
+My free time is too limited to get these things done without holding back the much needed fixes in 2.0.0 .
+They will either be done when time permits or, perhaps, you might want to tackle some of this?
 
-- There is currently no built-in way of accessing typeguards from paths their types may be associated with.
-- Models are not reused in or imported by this emitter. Reasoning involves "no runtime overhead either way", "simpler code", "self-contained emitter modules" and "you're not supposed to rummage around in the generated files anyway, just import them"; this has been touched upon in [#4](https://github.com/crowbait/typespec-typescript-emitter/issues/4#issuecomment-2720955282) and [#6](https://github.com/crowbait/typespec-typescript-emitter/issues/6#issuecomment-3049999155).
+- [ ] additional tests (the current testing setup is by no means exhaustive)
+  - [ ] `extends` on models, including `is` and spread notation
+  - [ ] imports from other files; are naming collisions still possible?
+  - [ ] thorough tests on imports and reuses for all emitted type kinds (model, union, enum, scalar)
+- [ ] support for generics
+- [ ] (with new option) typeguards referenced in / accessible from routes object
+- [ ] each file could export its "child" namespaces (from their respective files) via `export * from "rootNS.someNS.subNS.ts" as subNS;`, effectively making everything accessible by simply typing `rootNS.someNS.subNS.MyType`
+  - this will collide with imports from other files; these conflicts must be avoided when this option is set
+  - one dedicated file as "root" exports all specified root namespaces
+  - the `typemap` object can be used to generate lists of all namespaces within each namespace, using array reduction