@ -1,26 +1,31 @@
// Optimization: Right now, the state from parents is copied into the children. _Technically_ we could save the state on the root
/** @typedef {{ type: 'head' | 'body', content: string }} TNode */
// and simply have the children inherit that state and re-expose it through getters. This could save memory but probably isn't worth it.
/** @typedef {{ [key in TNode['type']]: string }} AccumulatedContent */
/** @typedef {{ start: number, end: number, fn: (content: AccumulatedContent) => AccumulatedContent | Promise<AccumulatedContent> }} Compaction */
// TODO we test for `instanceof AsyncContentTree` in some tight loops -- we might optimize
// by giving the tree a symbol property and checking that instead if we can actually notice any impact
/ * * / * *
* / * *
* A base class for payloads . Payloads are basically a tree of ` string | Payload ` s , where each
* A base class for payloads . Payloads are basically a tree of ` string | Payload ` s , where each
* ` Payload ` in the tree represents work that may or may not have completed . A payload can be
* ` Payload ` in the tree represents work that may or may not have completed . A payload can be
* { @ link collect } ed to aggregate the content from itself and all of its children , but this will
* { @ link collect } ed to aggregate the content from itself and all of its children , but this will
* throw if any of the children are performing asynchronous work . A payload can also be collected
* throw if any of the children are performing asynchronous work . A payload can also be collected
* asynchronously with { @ link collect _async } , which will wait for all children to complete before
* asynchronously with { @ link collect _async } , which will wait for all children to complete before
* collecting their contents .
* collecting their contents .
*
* @ template { new ( parent : Partial < InstanceType < TSubclass >> ) => { } } TSubclass
* /
* /
class Base Payload { export class Payload {
/ * *
/ * *
* This is the magical type that represents the instance type of a subclass of this type .
* @ type { TNode [ 'type' ] }
* How does it work ? idk man but it does
* @ typedef { this & InstanceType < TSubclass > } Instance
* /
* /
type ;
/** @type {Payload | undefined} */
parent ;
/ * *
/ * *
* The contents of the payload .
* The contents of the payload .
* @ type { ( string | Instance ) [ ] }
* @ type { ( TNode | Payload ) [ ] }
* /
* /
out = [ ] ;
out = [ ] ;
@ -31,88 +36,158 @@ class BasePayload {
* /
* /
promise ;
promise ;
/ * *
* State which is associated with the content tree as a whole .
* It will be re - exposed , uncopied , on all children .
* @ type { TreeState }
* @ readonly
* /
global ;
/ * *
* State that is local to the branch it is declared in .
* It will be shallow - copied to all children .
* @ type { { select _value : string | undefined } }
* /
local ;
/ * *
* @ param { TreeState } [ global ]
* @ param { { select _value : string | undefined } } [ local ]
* @ param { Payload | undefined } [ parent ]
* @ param { TNode [ 'type' ] } [ type ]
* /
constructor ( global = new TreeState ( ) , local = { select _value : undefined } , parent , type ) {
this . global = global ;
this . local = { ... local } ;
this . parent = parent ;
this . type = type ? ? parent ? . type ? ? 'body' ;
}
/ * *
/ * *
* Create a child payload . The child payload inherits the state from the parent ,
* Create a child payload . The child payload inherits the state from the parent ,
* but has its own ` out ` array and ` promise ` property . The child payload is automatically
* but has its own ` out ` array and ` promise ` property . The child payload is automatically
* inserted into the parent payload ' s ` out ` array .
* inserted into the parent payload ' s ` out ` array .
* @ param { ( args : { $$payload : Instance } ) => void | Promise < void > } render
* @ param { ( tree : Payload ) => void | Promise < void > } render
* @ param { TNode [ 'type' ] } [ type ]
* @ returns { void }
* @ returns { void }
* /
* /
child ( render ) {
child ( render , type ) {
const child = this . # create _child _instance ( ) ;
const child = new Payload ( this . global , this . local , this , type ) ;
this . out . push ( child ) ;
this . out . push ( child ) ;
const result = render ( { $$payload : child } ) ;
const result = render ( child ) ;
if ( result instanceof Promise ) {
if ( result instanceof Promise ) {
child . promise = result ;
child . promise = result ;
}
}
}
}
/ * *
* This is a convenience function that allows pushing strings , and will automatically use the configured ` type ` of this
* payload . It 's fine to push content of a different type to the `out` array; it' s just more annoying to write .
* @ param { string } content
* /
push ( content ) {
this . out . push ( { type : this . type , content } ) ;
}
/ * *
/ * *
* Compact everything between ` start ` and ` end ` into a single payload , then call ` fn ` with the result of that payload .
* Compact everything between ` start ` and ` end ` into a single payload , then call ` fn ` with the result of that payload .
* The compacted payload will be sync if all of the children are sync and { @ link fn } is sync , otherwise it will be async .
* The compacted payload will be sync if all of the children are sync and { @ link fn } is sync , otherwise it will be async .
* @ param { { start : number , end ? : number , fn : ( value : string ) => string | Promise < string > } } args
* @ param { { start : number , end ? : number , fn : ( content: AccumulatedContent ) => AccumulatedContent | Promise < AccumulatedContent > } } args
* /
* /
compact ( { start , end = this . out . length , fn } ) {
compact ( { start , end = this . out . length , fn } ) {
const child = this . # create _child _instance ( ) ;
const child = new Payload ( this . global , this . local , this ) ;
const to _compact = this . out . splice ( start , end - start , child ) ;
const to _compact = this . out . splice ( start , end - start , child ) ;
const promises = BasePayload . # collect _promises ( to _compact , [ ] ) ;
const promises = . # collect _promises ( to _compact , [ ] ) ;
/** @param {string | Promise<string>} res */
/** @param { AccumulatedContent | Promise<AccumulatedContent >} res */
const push _result = ( res ) => {
const push _result = ( res ) => {
if ( typeof res === 'string' ) {
if ( res instanceof Promise ) {
child . out . push ( res ) ;
} else {
child . promise = res . then ( ( resolved ) => {
child . promise = res . then ( ( resolved ) => {
child. out . push ( resolved ) ;
Payload . # push _accumulated _content ( child , resolved ) ;
} ) ;
} ) ;
} else {
Payload . # push _accumulated _content ( child , res ) ;
}
}
} ;
} ;
if ( promises . length > 0 ) {
if ( promises . length > 0 ) {
// we have to wait for the accumulated work associated with all branches to complete,
// then we can accumulate their content to compact it.
child . promise = Promise . all ( promises )
child . promise = Promise . all ( promises )
. then ( ( ) => fn ( BasePayload . # collect _content ( to _compact ) ) )
. then ( ( ) => fn ( . # collect _content ( to _compact ) ) )
. then ( push _result ) ;
. then ( push _result ) ;
} else {
} else {
push _result ( fn ( Base Payload. # collect _content ( to _compact ) ) ) ;
push _result ( fn ( . # collect _content ( to _compact ) ) ) ;
}
}
}
}
/ * *
* @ returns { number [ ] }
* /
get _path ( ) {
return this . parent ? [ ... this . parent . get _path ( ) , this . parent . out . indexOf ( this ) ] : [ ] ;
}
/ * *
/ * *
* Waits for all child payloads to finish their blocking asynchronous work , then returns the generated content .
* Waits for all child payloads to finish their blocking asynchronous work , then returns the generated content .
* @ returns { Promise < string > }
* @ returns { Promise < AccumulatedContent > }
* /
* /
async collect _async ( ) {
async collect _async ( ) {
// TODO: Should probably use `Promise.allSettled` here just so we can report detailed errors
// TODO: Should probably use `Promise.allSettled` here just so we can report detailed errors
await Promise . all ( BasePayload . # collect _promises ( this . out , this . promise ? [ this . promise ] : [ ] ) ) ;
await Promise . all ( . # collect _promises ( this . out , this . promise ? [ this . promise ] : [ ] ) ) ;
return Base Payload. # collect _content ( this . out ) ;
return . # collect _content ( this . out ) ;
}
}
/ * *
/ * *
* Collect all of the code from the ` out ` array and return it as a string .
* Collect all of the code from the ` out ` array and return it as a string .
* @ returns { string }
* @ returns { AccumulatedContent }
* /
* /
collect ( ) {
collect ( ) {
const promises = Base Payload. # collect _promises ( this . out , this . promise ? [ this . promise ] : [ ] ) ;
const promises = . # collect _promises ( this . out , this . promise ? [ this . promise ] : [ ] ) ;
if ( promises . length > 0 ) {
if ( promises . length > 0 ) {
// TODO is there a good way to report where this is? Probably by using some sort of loc or stack trace in `child` creation
// TODO is there a good way to report where this is? Probably by using some sort of loc or stack trace in `child` creation
throw new Error ( 'Encountered an asynchronous component while rendering synchronously' ) ;
throw new Error ( 'Encountered an asynchronous component while rendering synchronously' ) ;
}
}
return BasePayload . # collect _content ( this . out ) ;
return Payload . # collect _content ( this . out ) ;
}
copy ( ) {
const copy = new Payload ( this . global , this . local , this . parent , this . type ) ;
copy . out = this . out . map ( ( item ) => ( item instanceof Payload ? item . copy ( ) : item ) ) ;
copy . promise = this . promise ;
return copy ;
}
/ * *
* @ param { Payload } other
* /
subsume ( other ) {
this . global . subsume ( other . global ) ;
this . local = other . local ;
this . out = other . out . map ( ( item ) => {
if ( item instanceof Payload ) {
item . subsume ( item ) ;
}
return item ;
} ) ;
this . promise = other . promise ;
this . type = other . type ;
}
}
/ * *
/ * *
* @ param { ( string | Instance ) [ ] } items
* @ param { ( TNode | Payload ) [ ] } items
* @ param { Promise < void > [ ] } promises
* @ param { Promise < void > [ ] } promises
* @ returns { Promise < void > [ ] }
* @ returns { Promise < void > [ ] }
* /
* /
static # collect _promises ( items , promises ) {
static # collect _promises ( items , promises ) {
for ( const item of items ) {
for ( const item of items ) {
if ( typeof item !== 'string' ) {
if ( item instanceof Payload ) {
if ( item . promise ) {
if ( item . promise ) {
promises . push ( item . promise ) ;
promises . push ( item . promise ) ;
}
}
BasePayload . # collect _promises ( item . out , promises ) ;
. # collect _promises ( item . out , promises ) ;
}
}
}
}
return promises ;
return promises ;
@ -120,46 +195,41 @@ class BasePayload {
/ * *
/ * *
* Collect all of the code from the ` out ` array and return it as a string .
* Collect all of the code from the ` out ` array and return it as a string .
* @ param { ( string | Instance ) [ ] } items
* @ param { ( TNode | Payload ) [ ] } items
* @ returns { string }
* @ param { AccumulatedContent } content
* @ returns { AccumulatedContent }
* /
* /
static # collect _content ( items ) {
static # collect _content ( items , content = { head : '' , body : '' } ) {
// TODO throw in `async` mode
let content = '' ;
for ( const item of items ) {
for ( const item of items ) {
if ( typeof item === 'string' ) {
if ( item instanceof Payload ) {
content += item ;
Payload. # collect _content ( item . out , content ) ;
} else {
} else {
content += BasePayload . # collect _content ( item . out ) ;
content [ item . type ] += item . content ;
}
}
}
}
return content ;
return content ;
}
}
/** @returns {Instance} */
/ * *
# create _child _instance ( ) {
* @ param { Payload } tree
// @ts-expect-error - This lets us create an instance of the subclass of this class. Type-danger is constrained by the fact that TSubclass must accept an instance of itself in its constructor.
* @ param { AccumulatedContent } accumulated _content
return new this . constructor ( this ) ;
* /
static # push _accumulated _content ( tree , accumulated _content ) {
for ( const [ type , content ] of Object . entries ( accumulated _content ) ) {
tree . out . push ( { type : /** @type {TNode['type']} */ ( type ) , content } ) ;
}
}
}
} }
/ * * export class TreeState {
* @ extends { BasePayload < typeof HeadPayload > }
* /
export class HeadPayload extends BasePayload {
/** @type {Set<{ hash: string; code: string }>} */
# css ;
/** @type {() => string} */
/** @type {() => string} */
# uid ;
# uid ;
/ * *
/** @type {Set<{ hash: string; code: string }>} */
* This is a string or a promise so that the last write "wins" synchronously ,
# css ;
* as opposed to writes coming in whenever it happens to during async work .
* It ' s boxed so that the same value is shared across all children .
/** @type {TreeHeadState} */
* @ type { { value : string | Promise < string > } }
# head ;
* /
# title ;
get css ( ) {
get css ( ) {
return this . # css ;
return this . # css ;
@ -169,60 +239,48 @@ export class HeadPayload extends BasePayload {
return this . # uid ;
return this . # uid ;
}
}
get title ( ) {
get head ( ) {
return this . # title ;
return this . # head ;
}
}
/ * *
/ * *
* @ param { { css ? : Set < { hash : string ; code : string } > , title ? : { value : string | Promise < string > } , uid ? : ( ) => string } } args
* @ param { string } [ id _prefix ]
* /
* /
constructor ( { css = new Set ( ) , title = { value : '' } , uid = ( ) => '' } = { } ) {
constructor ( id _prefix = '' ) {
super ( ) ;
this . # uid = props _id _generator ( id _prefix ) ;
this . # css = css ;
this . # css = new Set ( ) ;
this . # title = title ;
this . # head = new TreeHeadState ( this . # uid ) ;
this . # uid = uid ;
}
}
copy ( ) {
copy ( ) {
const head _payload = new HeadPayload ( {
const state = new TreeState ( ) ;
css : new Set ( this . # css ) ,
state . # css = new Set ( this . # css ) ;
title : this . title ,
state . # head = this . # head . copy ( ) ;
uid : this . # uid
state . # uid = this . # uid ;
} ) ;
return state ;
head _payload . promise = this . promise ;
head _payload . out = [ ... this . out ] ;
return head _payload ;
}
}
/ * *
/ * *
* @ param { HeadPayload } other
* @ param { TreeState } other
* /
* /
subsume ( other ) {
subsume ( other ) {
// @ts-expect-error
this . out = [ ... other . out ] ;
this . promise = other . promise ;
this . # css = other . # css ;
this . # css = other . # css ;
this . # title = other . # title ;
this . # uid = other . # uid ;
this . # uid = other . # uid ;
this . # head . subsume ( other . # head ) ;
}
}
} }
/ * * export class TreeHeadState {
* @ extends { BasePayload < typeof Payload > }
* /
export class Payload extends BasePayload {
/** @type {() => string} */
# uid ;
/** @type {Set<{ hash: string; code: string }>} */
/** @type {Set<{ hash: string; code: string }>} */
# css ;
# css = new Set ( ) ;
/** @type { HeadPayload } */
/** @type {() => string} */
# head ;
# uid = ( ) => '' ;
/** @type {string | undefined} */
/ * *
select _value ;
* @ type { { path : number [ ] , value : string } }
* /
# title = { path : [ ] , value : '' } ;
get css ( ) {
get css ( ) {
return this . # css ;
return this . # css ;
@ -232,51 +290,57 @@ export class Payload extends BasePayload {
return this . # uid ;
return this . # uid ;
}
}
get head ( ) {
get title ( ) {
return this . # head ;
return this . # title ;
}
set title ( value ) {
// perform a depth-first (lexicographic) comparison using the path. Reject sets
// from earlier than or equal to the current value.
const contender _path = value . path ;
const current _path = this . # title . path ;
const max _len = Math . max ( contender _path . length , current _path . length ) ;
for ( let i = 0 ; i < max _len ; i ++ ) {
const contender _segment = contender _path [ i ] ;
const current _segment = current _path [ i ] ;
// contender shorter than current and all previous segments equal -> earlier
if ( contender _segment === undefined ) return ;
// current shorter than contender and all previous segments equal -> contender is later
if ( current _segment === undefined || contender _segment > current _segment ) {
this . # title . path = value . path ;
this . # title . value = value . value ;
return ;
}
if ( contender _segment < current _segment ) return ;
// else equal -> continue
}
// paths are equal -> keep current value (do nothing)
}
}
/ * *
/ * *
* @ param { { id _prefix ? : string , head ? : HeadPayload , uid ? : ( ) => string , css ? : Set < { hash : string ; code : string } > , select _value ? : string | undefined } } args
* @ param { ) => string
* /
* /
constructor ( {
constructor ( uid ) {
id _prefix = '' ,
head = new HeadPayload ( ) ,
uid = props _id _generator ( id _prefix ) ,
css = new Set ( ) ,
select _value
} = { } ) {
super ( ) ;
this . # uid = uid ;
this . # uid = uid ;
this . # css = css ;
this . # css = new Set ( ) ;
this . # head = head ;
this . # title = { path : [ ] , value : '' } ;
this . select _value = select _value ;
}
}
copy ( ) {
copy ( ) {
const payload = new Payload ( {
const head _state = new TreeHeadState ( this . # uid ) ;
css : new Set ( this . # css ) ,
head _state . # css = new Set ( this . # css ) ;
uid : this . # uid ,
head _state . # title = this . title ;
head : this . # head . copy ( )
return head _state ;
} ) ;
payload . select _value = this . select _value ;
payload . promise = this . promise ;
payload . out = [ ... this . out ] ;
return payload ;
}
}
/ * *
/ * *
* @ param { Payload } other
* @ param { TreeHeadState } other
* /
* /
subsume ( other ) {
subsume ( other ) {
// @ts-expect-error
this . out = [ ... other . out ] ;
this . promise = other . promise ;
this . select _value = other . select _value ;
this . # css = other . # css ;
this . # css = other . # css ;
this . # title = other . # title ;
this . # uid = other . # uid ;
this . # uid = other . # uid ;
this . # head . subsume ( other . # head ) ;
}
}
} }
S. Elliott Johnson
1 week ago