Skip to content

Commit 629a1fe

Browse files
jasonkuhrtjasonkuhrt
authored
improve(lib/builder): refine jsdoc and terms (#1270)
1 parent 2299e33 commit 629a1fe

File tree

9 files changed

+241
-105
lines changed

9 files changed

+241
-105
lines changed

‎src/client/builderExtensions/anyware.ts

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -18,7 +18,7 @@ export interface Anyware<$Arguments extends Builder.Extension.Parameters<Builder
1818
interceptor: AnywareLib.Interceptor.InferConstructor<
1919
RequestPipeline['spec']
2020
>,
21-
) => Builder.Definition.MaterializeWithNewContext<$Arguments['chain'], $Arguments['context']>
21+
) => Builder.Definition.MaterializeWith<$Arguments['definition'], $Arguments['context']>
2222
}
2323

2424
export const builderExtensionAnyware = Builder.Extension.create<BuilderExtensionAnyware>((builder, context) => {

‎src/client/builderExtensions/scalar.ts

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -34,8 +34,8 @@ type ScalarMethod<$Args extends Builder.Extension.Parameters<BuilderExtensionSca
3434
decode: (value: string) => $Decoded
3535
encode: (value: $Decoded) => string
3636
},
37-
): Builder.Definition.MaterializeWithNewContext<
38-
$Args['chain'],
37+
): Builder.Definition.MaterializeWith<
38+
$Args['definition'],
3939
ConfigManager.SetAtPath<
4040
$Args['context'],
4141
['scalars'],
@@ -53,8 +53,8 @@ type ScalarMethod<$Args extends Builder.Extension.Parameters<BuilderExtensionSca
5353
*/
5454
<$Scalar extends Schema.Scalar<GlobalRegistry.GetOrGeneric<$Args['context']['name']>['schema']['scalarNamesUnion']>>(
5555
scalar: $Scalar,
56-
): Builder.Definition.MaterializeWithNewContext<
57-
$Args['chain'],
56+
): Builder.Definition.MaterializeWith<
57+
$Args['definition'],
5858
ConfigManager.SetAtPath<
5959
$Args['context'],
6060
['scalars'],

‎src/client/builderExtensions/use.ts

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -19,12 +19,12 @@ export interface Use<$Args extends Builder.Extension.Parameters<BuilderExtension
1919
export type UseExtensionDo<
2020
$Args extends Builder.Extension.Parameters<BuilderExtensionUse>,
2121
$Extension extends Extension,
22-
> = Builder.Definition.MaterializeWithNewContext<
22+
> = Builder.Definition.MaterializeWith<
2323
// Apply any builder extensions.
2424
(
2525
ConfigManager.GetOptional<$Extension, ['builder', 'type']> extends Builder.Extension
26-
? Builder.Definition.AddExtension<$Args['chain'], ConfigManager.GetOptional<$Extension, ['builder', 'type']>>
27-
: $Args['chain']
26+
? Builder.Definition.AddExtension<$Args['definition'], ConfigManager.GetOptional<$Extension, ['builder', 'type']>>
27+
: $Args['definition']
2828
),
2929
// Extend context.
3030
ConfigManager.SetMany<

‎src/client/builderExtensions/with.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -20,8 +20,8 @@ export interface With<$Args extends Builder.Extension.Parameters<BuilderExtensio
2020
// todo fixme
2121
// eslint-disable-next-line
2222
// @ts-ignore Passes after generation
23-
) => Builder.Definition.MaterializeWithNewContext<
24-
$Args['chain'],
23+
) => Builder.Definition.MaterializeWith<
24+
$Args['definition'],
2525
ConfigManager.SetProperties<
2626
$Args['context'],
2727
{

‎src/client/client.ts

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -33,19 +33,21 @@ import { type NormalizeInput } from './Settings/InputToConfig.js'
3333
// >
3434
// >
3535

36-
export type Client<$Context extends Context> = Builder.Definition.MaterializeWithNewContext<
37-
Builder.Definition.Create<[
38-
BuilderExtensionInternal,
39-
BuilderExtensionRequestMethods,
40-
BuilderExtensionWith,
41-
BuilderExtensionUse,
42-
BuilderExtensionAnyware,
43-
BuilderExtensionGql,
44-
BuilderExtensionScalar,
45-
]>,
36+
export type Client<$Context extends Context> = Builder.Definition.MaterializeWith<
37+
ClientDefinition,
4638
$Context
4739
>
4840

41+
type ClientDefinition = Builder.Definition.Create<[
42+
BuilderExtensionInternal,
43+
BuilderExtensionRequestMethods,
44+
BuilderExtensionWith,
45+
BuilderExtensionUse,
46+
BuilderExtensionAnyware,
47+
BuilderExtensionGql,
48+
BuilderExtensionScalar,
49+
]>
50+
4951
// dprint-ignore
5052
type Create = <$Input extends InputStatic>(input: Exact<$Input, InputStatic>) =>
5153
// todo fixme

‎src/extensions/Throws/Throws.ts

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -38,8 +38,8 @@ interface BuilderExtension_<$Args extends Builder.Extension.Parameters<BuilderEx
3838
/**
3939
* TODO
4040
*/
41-
throws: () => Builder.Definition.MaterializeWithNewContext<
42-
$Args['chain'],
41+
throws: () => Builder.Definition.MaterializeWith<
42+
$Args['definition'],
4343
ConfigManager.UpdateAtKey<
4444
$Args['context'],
4545
'config',

‎src/lib/builder/Definition.ts

Lines changed: 119 additions & 56 deletions
Original file line numberDiff line numberDiff line change
@@ -5,21 +5,22 @@ import type { TypeFunction } from '../type-function/__.js'
55
import type { Context, Extension } from './Extension.js'
66

77
/**
8-
* A chain. Type level function with extensions.
9-
* When called, it returns itself with the given extensions.
8+
* A builder definition.
9+
* Technically it is a type level function with additional properties.
10+
* When called, returns itself with the given extensions attached as a property.
1011
*/
1112
export interface Definition_<$Extensions extends [...Extension[]] = [...Extension[]]> extends TypeFunction.Fn {
1213
extensions: $Extensions
1314
return: Definition_<AssertExtends<this['params'], Extension[]>>
1415
}
1516

16-
type InvokeDefinition<_ extends Definition_, $Arguments extends [...Extension[]]> = TypeFunction.Call<
17-
_,
17+
type InvokeDefinition<$Definition extends Definition_, $Arguments extends [...Extension[]]> = TypeFunction.Call<
18+
$Definition,
1819
$Arguments
1920
>
2021

2122
/**
22-
* An empty chain definition. Useful for creation of new chains.
23+
* A definition literal, empty. Useful for creation of new builders.
2324
*/
2425
export type Empty = Definition_<[]>
2526

@@ -29,107 +30,169 @@ export type Empty = Definition_<[]>
2930
export type Create<$Extensions extends [...Extension[]]> = AddExtensions<Empty, $Extensions>
3031

3132
/**
32-
* Extend the definition with many extensions. Refer to `Extend` for more details.
33+
* Extend the definition with many extensions. See {@link AddExtension} for details.
3334
*/
3435
// dprint-ignore
35-
export type AddExtensions<$Chain_ extends Definition_, $Extensions extends [...Extension[]]> =
36+
export type AddExtensions<$Definition extends Definition_, $Extensions extends [...Extension[]]> =
3637
$Extensions extends [infer $FirstExtension extends Extension, ...infer $RestExtensions extends Extension[]]
37-
? AddExtensions<AddExtension<$Chain_, $FirstExtension>, $RestExtensions>
38-
: $Chain_
38+
? AddExtensions<AddExtension<$Definition, $FirstExtension>, $RestExtensions>
39+
: $Definition
3940

4041
/**
4142
* Extend the definition. During materialization the extension can contribute properties
4243
* that make up the final builder.
4344
*/
4445
// dprint-ignore
45-
export type AddExtension<$Chain_ extends Definition_, $Extension_ extends Extension> =
46-
InvokeDefinition<$Chain_, [...$Chain_['extensions'], $Extension_]>
46+
export type AddExtension<$definition_ extends Definition_, $Extension_ extends Extension> =
47+
InvokeDefinition<$definition_, [...$definition_['extensions'], $Extension_]>
4748

4849
//
4950
// Materialize Utilities
5051
//
5152

53+
/**
54+
* Materialize the definition using each extension's generic context type.
55+
*
56+
* Each extension will be invoked with its own generic context type.
57+
* Then results will be merged to produce the builder object.
58+
*
59+
* All extensions' generic context types will be merged to produce
60+
* the builder object context property.
61+
*/
5262
// dprint-ignore
53-
export type MaterializeGeneric<$Chain_ extends Definition_> =
63+
export type MaterializeGeneric<$Definition extends Definition_> =
5464
Simplify<
5565
Private.Add<
5666
{
57-
chain: $Chain_,
58-
context: Tuple.IntersectItems<
59-
MaterializeExtensionsGenericContext<$Chain_['extensions']>
60-
>
67+
definition: $Definition,
68+
context: MaterializeGeneric_Context<$Definition>
6169
},
62-
Tuple.IntersectItems<
63-
MaterializeExtensionsGeneric<$Chain_, $Chain_['extensions']>
64-
>
70+
MaterializeGeneric_Extensions<$Definition>
6571
>
6672
>
6773

6874
// dprint-ignore
69-
type MaterializeExtensionsGeneric<$Chain_ extends Definition_, $Extensions extends [...Extension[]]> = {
70-
[$Index in keyof $Extensions]: Extension.Invoke<$Extensions[$Index], {
71-
chain: $Chain_,
72-
context: $Extensions[$Index]['context']
73-
}>
74-
}
75+
type MaterializeGeneric_Extensions<$Definition extends Definition_> =
76+
Tuple.IntersectItems<
77+
MaterializeGeneric_Extensions_<
78+
$Definition,
79+
$Definition['extensions']
80+
>
81+
>
7582
// dprint-ignore
76-
type MaterializeExtensionsGenericContext<$Extensions extends [...Extension[]]> = {
83+
type MaterializeGeneric_Extensions_<
84+
$Definition extends Definition_,
85+
$Extensions extends [...Extension[]]
86+
> = {
87+
[$Index in keyof $Extensions]:
88+
Extension.Invoke<$Extensions[$Index], {
89+
definition: $Definition,
90+
context: $Extensions[$Index]['context'],
91+
}>
92+
}
93+
94+
type MaterializeGeneric_Context<$Definition extends Definition_> = Tuple.IntersectItems<
95+
MaterializeGeneric_Context_<$Definition['extensions']>
96+
>
97+
type MaterializeGeneric_Context_<$Extensions extends [...Extension[]]> = {
7798
[$Index in keyof $Extensions]: $Extensions[$Index]['context']
7899
}
79100

101+
//
102+
//
103+
// ---------------------------------------------------------------------------------------------
104+
//
105+
//
106+
107+
/**
108+
* Materialize the definition using each extension's empty context type.
109+
*
110+
* Each extension will be invoked with its own empty context.
111+
* Then results will be merged to produce the builder object.
112+
*
113+
* All extensions' empty context types will be merged to produce
114+
* the builder object context property.
115+
*/
80116
// dprint-ignore
81-
export type MaterializeSpecific<$Chain_ extends Definition_> =
117+
export type MaterializeEmpty<$Definition extends Definition_> =
82118
Simplify<
83119
Private.Add<
84120
{
85-
chain: $Chain_,
86-
context: Tuple.IntersectItems<
87-
MaterializeExtensionsInitialContext<$Chain_['extensions']>
88-
>
121+
definition: $Definition,
122+
context: MaterializeEmpty_Context<$Definition>,
89123
},
90124
Tuple.IntersectItems<
91-
MaterializeExtensionsInitial<$Chain_, $Chain_['extensions']>
125+
MaterializeEmpty_Extensions<$Definition, $Definition['extensions']>
92126
>
93127
>
94128
>
95129

96130
// dprint-ignore
97-
type MaterializeExtensionsInitial<$Chain_ extends Definition_, $Extensions extends [...Extension[]]> = {
131+
type MaterializeEmpty_Extensions<
132+
$Definition extends Definition_,
133+
$Extensions extends [...Extension[]]
134+
> = {
98135
[$Index in keyof $Extensions]: Extension.Invoke<$Extensions[$Index], {
99-
chain: $Chain_,
136+
definition: $Definition,
100137
context: $Extensions[$Index]['contextEmpty']
101138
}>
102139
}
103140
// dprint-ignore
104-
type MaterializeExtensionsInitialContext<$Extensions extends [...Extension[]]> = {
141+
type MaterializeEmpty_Context<$Definition extends Definition_> =
142+
Tuple.IntersectItems<
143+
MaterializeEmpty_Context_<$Definition['extensions']>
144+
>
145+
// dprint-ignore
146+
type MaterializeEmpty_Context_<$Extensions extends [...Extension[]]> = {
105147
[$Index in keyof $Extensions]: $Extensions[$Index]['contextEmpty']
106148
}
107149

150+
//
151+
//
152+
// ---------------------------------------------------------------------------------------------
153+
//
154+
//
155+
156+
/**
157+
* Materialize the definition with a new context.
158+
*
159+
* Each extension will be invoked with the given context.
160+
* Then results will be merged to produce the builder object.
161+
*
162+
* The given context will be used as-is for the builder object context property.
163+
*/
108164
// dprint-ignore
109-
export type MaterializeWithNewContext<$Chain_ extends Definition_, $Context extends Context> =
110-
// Simplify<
111-
Private.Add<
112-
{
113-
chain: $Chain_,
114-
context: $Context
115-
},
116-
Tuple.IntersectItems<
117-
MaterializeExtensionsWithNewState<
118-
$Chain_,
119-
$Context,
120-
$Chain_['extensions']
121-
>
165+
export type MaterializeWith<
166+
$Definition extends Definition_,
167+
$Context extends Context
168+
> =
169+
170+
Private.Add<
171+
{
172+
definition: $Definition,
173+
context: $Context
174+
},
175+
Tuple.IntersectItems<
176+
MaterializeWith_Extensions<
177+
$Definition,
178+
$Definition['extensions'],
179+
$Context
122180
>
123181
>
124-
// >
182+
>
125183

126-
type MaterializeExtensionsWithNewState<
127-
$Chain_ extends Definition_,
128-
$Context extends Context,
184+
// dprint-ignore
185+
type MaterializeWith_Extensions<
186+
$Definition extends Definition_,
129187
$Extensions extends [...Extension[]],
188+
$Context extends Context,
130189
> = {
131-
[$Index in keyof $Extensions]: Extension.Invoke<
132-
$Extensions[$Index],
133-
{ chain: $Chain_; context: $Context }
134-
>
190+
[$Index in keyof $Extensions]:
191+
Extension.Invoke<
192+
$Extensions[$Index],
193+
{
194+
definition: $Definition
195+
context: $Context
196+
}
197+
>
135198
}

0 commit comments

Comments
 (0)