@sjcrh/proteinpaint-types 2.86.0 → 2.87.1

package/src/terms/tw.ts

@@ -0,0 +1,38 @@
+import { BaseQ, BaseTW, Term } from './term.ts'
+import { CategoricalQ, CategoricalTW } from './categorical.ts'
+import { NumericQ, NumericTW } from './numeric.ts'
+import { SnpsQ, SnpsTW } from './snps.ts'
+import { ConditionQ } from './condition.ts'
+import { GeneVariantQ } from './geneVariant.ts'
+import { SampleLstQ } from './samplelst.ts'
+
+export type TermWrapper = CategoricalTW | NumericTW | SnpsTW | (BaseTW & { term: Term; q: Q })
+export type TwLst = TermWrapper[]
+
+export type Q = BaseQ | CategoricalQ | ConditionQ | NumericQ | GeneVariantQ | SampleLstQ | SnpsQ
+
+export type RawTW =
+	//{ id: string } | RawCatTW
+	//
+	// BELOW TYPE IS NOT TESTED, only being used to compare tsc type checking behavior
+	// between non-union versus type-unions, which way is easier to code against
+	{
+		id?: string
+		term?: {
+			type: 'categorical' | 'condition'
+			[key: string | number]: any
+		}
+		q?: {
+			//predefined_groupset_idx?: number
+			//customset?: any
+			[key: string]: any
+			//type?: string //'custom-groupset' |
+			//customset?: any
+		}
+		isAtomic?: true
+		$id?: string
+	}
+
+export interface TwHandler {
+	render?: (opts?: any) => void
+}

package/src/terms/updated-types.ts

@@ -0,0 +1,9 @@
+// temporary code file to hold updated type definitions
+// as part of the tw router/handler refactor
+
+import { CatTWTypes, CategoricalQ } from './categorical.ts'
+import { NumTWTypes, NumericQ } from './numeric.ts'
+
+export type TermWrapper = CatTWTypes | NumTWTypes
+
+export type Q = CategoricalQ | NumericQ // | other q

package/src/termsetting.ts

@@ -0,0 +1,197 @@
+// TODO: will deprecate this code, should use client/termsetting/types.ts instead
+import { VocabApi } from './vocab.ts'
+import { TermWrapper, Q } from './terms/tw.ts'
+import { Term } from './terms/term.ts'
+import { Filter } from './filter.ts'
+
+/*
+
+!!! 
+	For shared/types: 
+	- Declare only the types that are used in the request and response payloads, or in *both* client and server-side code
+	- Do not track client or server-specific type declarations here, those belong in the corresponding workspace code 
+!!!
+
+--------EXPORTED--------
+Dom
+Api
+NoTermPromptOptsEntry
+UseCase
+SampleCountsEntry
+Handler
+PillData
+TermSettingOpts
+InstanceDom
+TermSettingInstance
+
+*/
+
+/*** types supporting TermSettingOpts & PillData types ***/
+
+export type Dom = {
+	holder: Selection
+	tip: any //TODO Menu type??
+	tip2: any //same as above
+	nopilldiv?: Selection
+	pilldiv?: Selection
+	btnDiv?: Selection
+}
+
+export type NoTermPromptOptsEntry = {
+	isDictionary?: boolean
+	termtype?: string
+	text?: string
+	html?: string
+	q?: Q
+	/** whether or not opt is invalid */
+	invalid?: boolean
+	/** message displayed when opt is invalid */
+	invalidMsg?: string
+}
+
+type NumericContEditOptsEntry = {
+	scale: string
+	transform: string
+}
+
+export type UseCase = {
+	target: string
+	detail?: string //Maybe?
+	regressionType?: string //Maybe?
+	term1type?: string //Maybe? not documented
+}
+
+type DefaultQ4fillTW = {
+	[index: string]: Q
+}
+
+export type SampleCountsEntry = {
+	key: string
+	value: number //This maybe a string???
+	label?: string //Not documented?? in key or no?
+}
+
+export type Handler = {
+	getPillName: (d: any) => string
+	getPillStatus: (f?: any) => any
+	showEditMenu: (div: Selection) => void
+	validateQ?: (d: Q) => void
+	postMain?: () => void
+}
+
+type BaseTermSettingOpts = {
+	//Optional
+	abbrCutoff?: number
+	activeCohort?: number
+	disable_terms?: string[]
+	handler: Handler
+	noTermPromptOptions?: NoTermPromptOptsEntry[]
+}
+
+export type PillData = BaseTermSettingOpts & {
+	$id?: string
+	doNotHideTipInMain: boolean
+	dom: Dom
+	error?: string
+	filter?: Filter
+	q?: Q
+	sampleCounts?: SampleCountsEntry[]
+	term?: Term
+}
+
+export type TermSettingOpts = BaseTermSettingOpts & {
+	//Required
+	holder: any
+	vocabApi: VocabApi
+	//Optional
+	$id?: string
+	buttons?: string[] //replace, delete, info
+	defaultQ4fillTW?: DefaultQ4fillTW
+	menuOptions: string //all, edit, replace, remove
+	menuLayout?: string //horizonal, all
+	numericEditMenuVersion?: string[]
+	geneVariantEditMenuOnlyGrp?: boolean
+	numericContinuousEditOptions?: NumericContEditOptsEntry[]
+	placeholder?: string
+	placeholderIcon?: string //default '+'
+	renderAs: string //none
+	tip?: any //TODO: Menu type?
+	use_bins_less?: boolean
+	usecase?: UseCase
+	debug?: boolean | number //true or 1
+	//'snplocus' types
+	genomeObj?: any
+
+	//vocab??
+
+	// required callback function. argument is the updated termwrapper object
+	callback: (f: TermWrapper | null) => void
+
+	// ?
+	customFillTw?: (f: TermWrapper) => void
+
+	// to pass in purpose and context-specific arguments that will be merged to client request parameters
+	getBodyParams?: () => any
+}
+
+/*** types supporting TermSettingInstance type ***/
+
+export type InstanceDom = {
+	//Separate from the Dom outlined in termsetting.ts?????
+	//Required
+	holder: any
+	tip: any //TODO Menu type??
+	tip2: any //same as above
+	nopilldiv?: any
+	pilldiv?: any
+	btnDiv?: any
+	//Optional
+	customBinBoundaryInput?: any
+	customBinBoundaryPercentileCheckbox?: any
+	customBinLabelInput?: any
+	customBinRanges?: any
+	cutoff_div?: any
+	num_holder?: any
+	pill_termname?: any
+	rangeAndLabelDiv?: any
+}
+
+export type TermSettingInstance = {
+	activeCohort?: number
+	clickNoPillDiv?: any
+	dom: InstanceDom
+	doNotHideTipInMain?: boolean
+	disable_terms?: string[]
+	durations: { exit: number }
+	filter?: Filter
+	handler?: Handler
+	handlerByType?: { [index: string]: Handler }
+	hasError?: boolean
+	noTermPromptOptions?: NoTermPromptOptsEntry[]
+	opts: TermSettingOpts
+	placeholder: string | undefined
+	q: Q
+	term: Term
+	usecase?: UseCase
+	vocabApi: VocabApi
+
+	//Methods
+	/*
+	TODOs: 
+		- Move specifc methods to their own intersection instance type within in termsetting/handler/*.ts, out of main type
+	*/
+	cancelGroupsetting?: () => void
+	enterPill?: () => void
+	exitPill?: () => void
+	initUI: () => void
+	removeTerm?: () => void
+	runCallback: (f?: any) => any
+	setHandler?: (f: string) => any
+	showGeneSearch: (clickedElem: Element | null, event: MouseEvent) => void
+	showMenu: (event: MouseEvent, clickedElem: string | null, menuHolder: any) => void
+	showReuseMenu?: (div: any) => void
+	showTree: (holder: Selection, event?: MouseEvent) => void
+	tabCallback?: (event: any, tab: any) => void
+	updatePill?: () => void
+	updateUI: () => void
+}

package/src/test/numeric.type.spec.ts

@@ -0,0 +1,275 @@
+import { StartUnboundedBin, StopUnboundedBin, FullyBoundedBin, NumericTerm } from '../terms/numeric'
+
+/*
+	Non-asserted type definition tests 
+	
+	For training only 
+	- these tests are not meant to be written for all declared types
+	
+	- meant for simple "sanity check", that a declaration makes sense and CATCHES ERRORS
+	
+	- quick tests on lines commented with @ts-expect-error 
+		- remove a // @ts-expect-error comment to see error message as emitted by the tsc compiler
+		- fix the variable declaration value to match the expected type, tsc should emit "Unused '@ts-expect-error' directive"
+*/
+
+/*****************
+ * Simple tests
+ ******************/
+
+{
+	// in unit and integration spec files, use the numeric type definitions
+	// to make sure that test data matches expectations, otherwise incorrect
+	// test data can lead to false passing or failing tests.
+	const valid: NumericTerm = {
+		type: 'float',
+		id: 'someid',
+		name: 'Some Dosage',
+		bins: {
+			default: {
+				type: 'regular-bin',
+				bin_size: 1,
+				first_bin: {
+					startunbounded: true,
+					stop: 1
+				}
+			},
+			less: {
+				type: 'custom-bin',
+				lst: [{ start: 0, stop: 1 }]
+			}
+		}
+	}
+
+	// @ts-expect-error, wrong term.type
+	const A: NumericTerm = { name: 'test', type: 'categorical' }
+	// @ts-expect-error, missing other required properties
+	const B: NumericTerm = { type: 'integer' }
+	const C: NumericTerm = {
+		// @ts-expect-error, should be string
+		name: 7,
+		type: 'integer',
+		bins: {
+			default: {
+				type: 'regular-bin',
+				bin_size: 1,
+				// tsc can detect type errors for deeply nested property values
+				// @ts-expect-error, does not match either StartUnboundedBin | FullyBoundedBin
+				first_bin: {
+					stop: 1
+				}
+			},
+			less: {
+				type: 'custom-bin',
+				// @ts-expect-error, empty lst array
+				lst: []
+			}
+		}
+	}
+}
+
+/*************************
+ * !!! How NOT to type !!!
+ **************************/
+
+// Example of a bad type declaration, where everything is optional.
+// Avoid declaring types with lots of optional properties, unless that's really expected.
+// In the PP codebase, a union of types is more likely to be the correct way to declare
+// a type with mutually exlusive properties based on, for example, term.type or gene variant value dt number.
+type UselessBinType = {
+	startunbounded?: boolean
+	startinclusive?: boolean
+	start?: number
+	stop?: number
+	stopinclusive?: boolean
+	stopunbounded?: boolean
+}
+
+{
+	// The UselesBinType matches objects with conflicting property values, which does not make sense.
+	// We want tsc to emit an error when unallowed, non-sensical combination of properties exist.
+	//
+	// For example, it does not make sense for a bin to have these combinations of property-values:
+	// - startunbounded: true and startinclusive: true    // cannot "contain" infinity
+	// - startunbounded: true and start: 0                // conflict, start is supposed to be unbounded and yet is assigned a finite value
+	// - startunbounded: true and stopunbounded: true     // an infinite bin
+	//
+	// Many other pairing of the property-values below do not make sense.
+	// Note that running the tsc on this file does not emit an error, but it should for values that do not make sense.
+	// To get tsc to emit errors, we should use the bin types from server/shared/types/terms/numeric.ts,
+	// or from the 'better' bin type examples farther down below (which will require more code changes).
+	const A: UselessBinType = {
+		startunbounded: true,
+		startinclusive: true,
+		start: 0,
+		stop: 1,
+		stopinclusive: true,
+		stopunbounded: true
+	}
+
+	// no error is thrown by an empty object because all properties are optional,
+	// but we want tsc to emit an error in this scenario
+	const B: UselessBinType = {}
+	// @ts-expect-error, not fully useless since an error is thrown because 'extraProp' is not defined as an optional property
+	B.extraProp = 'test'
+}
+
+/********************************************
+ * Testing types that are able to catch errors
+ *********************************************/
+
+// Start unbounded Bin
+{
+	// valid example
+	const A: StartUnboundedBin = {
+		startunbounded: true,
+		stop: 1
+	}
+
+	// invalid examples
+	// @ts-expect-error, conflict between startunbounded and start values
+	const B: StartUnboundedBin = { startunbounded: true, start: 0, stop: 1 }
+	// @ts-expect-error, missing start value
+	const C: StartUnboundedBin = { startunbounded: true }
+	// @ts-expect-error, conflict between unbounded flags and assigned finite values for start, stop
+	const D: StartUnboundedBin = { startunbounded: true, start: 0, stop: 1, stopunbounded: true }
+	// @ts-expect-error, missing properties
+	const E: StartUnboundedBin = {}
+	// @ts-expect-error, adding a property that was not defined for this type
+	E.extraProp = 'test'
+}
+
+// Stop unbounded bin
+{
+	// valid example
+	const A: StopUnboundedBin = {
+		stopunbounded: true,
+		start: 0
+	}
+
+	// invalid examples
+	// @ts-expect-error, conflict between stopunbounded and stop values
+	const B: StopUnboundedBin = { stopunbounded: true, start: 0, stop: 1 }
+	// @ts-expect-error, missing stop value
+	const C: StopUnboundedBin = { stopunbounded: true }
+	// @ts-expect-error, conflict between unbounded flags and assigned finite values for start, stop
+	const D: StopUnboundedBin = { startunbounded: true, start: 0, stop: 1, stopunbounded: true }
+}
+
+// Fully bounded bin
+{
+	// valid example
+	const A: FullyBoundedBin = {
+		startinclusive: true,
+		start: 0,
+		stop: 1
+	}
+
+	// invalid examples
+	// @ts-expect-error, missing start value
+	const B: FullyBoundedBin = { stop: 1 }
+	// @ts-expect-error, missing stop value
+	const C: FullyBoundedBin = { start: 0 }
+}
+
+/*** test of union type being fed into a subtype-specific "handler" function ***/
+// to be used as a 'generic' argument
+type NumericBin = StartUnboundedBin | StopUnboundedBin | FullyBoundedBin
+
+const handlers = {
+	startUnbounded(bin: StartUnboundedBin) {
+		console.log(bin)
+	},
+	fullyBounded(bin: FullyBoundedBin) {
+		console.log(bin)
+	},
+	stopUnbounded(bin: StopUnboundedBin) {
+		console.log(bin)
+	}
+}
+
+/**********************************************************************
+ * Test that tsc can infer that a type can be derived from
+ * a union of types. This is important for the general approach
+ * in the PP codebase to route arguments to specific handler functions.
+ ***********************************************************************/
+
+// these functions routes the bin argument to the correct handler function
+function correctlyTypedProcessBin(bin: NumericBin) {
+	if (bin.startunbounded) handlers.startUnbounded(bin as StartUnboundedBin)
+	else if (bin.stopunbounded) handlers.stopUnbounded(bin as StopUnboundedBin)
+	else handlers.fullyBounded(bin as FullyBoundedBin)
+}
+
+// not declared as part of the NumericBin type
+type NonNumericBin = { fake: true }
+// even though has an extra property compared to FullyBoundedBin,
+// the tsc compiler would consider this equivalent
+type LikeFullyBoundedBin = {
+	start: number
+	stop: number
+	test: boolean
+}
+
+function incorrectProcessBin(bin: FullyBoundedBin) {
+	// @ts-expect-error, the argument type is not StartUnboundedBin
+	if (bin.startunbounded) handlers.startUnbounded(bin as StartUnboundedBin)
+	// @ts-expect-error, the argument type is not StopUnboundedBin
+	else if (bin.stopunbounded) handlers.stopUnbounded(bin as StopUnboundedBin)
+	else {
+		// @ts-expect-error, expects StartUnbounded as argument type
+		handlers.startUnbounded(bin as FullyBoundedBin)
+		// @ts-expect-error, expects StopUnbounded as argument type
+		handlers.stopUnbounded(bin as FullyBoundedBin)
+		// @ts-expect-error, since this function's argument type (NumericBin) does not include NonNumericBin
+		handlers.fullyBounded(bin as NonNumericBinType)
+		// !!! SHOULD WORK !!!
+		handlers.fullyBounded(bin as LikeFullyBoundedBin)
+		// !!! SHOULD WORK !!!
+		handlers.fullyBounded(bin as FullyBoundedBin)
+	}
+}
+
+/************************************************************************
+ * Examples of better ways to define data structures to proactively avoid
+ * any chance of having flag values that may conflict with each other
+ *************************************************************************/
+
+// Example of better type declarations
+//
+// NOTE: The bin type declarations in server/shared/types/terms/numeric.ts are good for now,
+// the types below are meant to illustrate that there are different ways to write types that work.
+//
+// TODO: Use these better types, which will require code changes
+//
+type BetterStartUnboundedBin = {
+	stop: number
+	// by not using a flag, the 'inclusive' property completely avoids unintentionally having
+	// `startinclusive: true && stopinclusive: true` at the same time
+	inclusive: 'stop'
+}
+
+// NOTE: This approach also lessens the number of attributes/properties to define.
+// A problem with flags is it's very easy to have too many of them, and each one has to be defined,
+// and if they are mutually exclusive, most of the time that is not readily apparent.
+type BetterStopUnboundedBin = {
+	start: number
+	inclusive: 'start'
+}
+
+type BetterFullyBoundedBin = {
+	start: number
+	stop: number
+	// for numeric bins that are NOT standalone, using `inclusive: 'both'` will lead to conflict,
+	// since adjoining bins can both contain the same boundary value
+	inclusive: 'start' | 'stop'
+}
+
+type StandaloneBin = {
+	start: number
+	stop: number
+	// for standalone bins, the option to include both start and stop values will not lead to conflict
+	inclusive: 'start' | 'stop' | 'both'
+}
+
+type BetterNumericBin = BetterStartUnboundedBin | BetterStopUnboundedBin | BetterFullyBoundedBin | StandaloneBin

package/src/vocab.ts

@@ -0,0 +1,37 @@
+import { TermWrapper } from './terms/tw.ts'
+import { Term } from './terms/term.ts'
+import { Filter } from './filter.ts'
+import { UseCase } from './termsetting.ts'
+
+/*
+--------EXPORTED--------
+VocabApi
+
+*/
+
+//type QLst = [Partial<{ nextReuseId?: string }>, ...Q[]]
+
+export type VocabApi = {
+	termdbConfig: any
+	//Methods
+	cacheTermQ: (term: Term, q: any) => any
+	findTerm: (f: string, activeCohort: number, usecase: UseCase, x: string) => { lst: Term[] }
+	getCategories: (term: Term, filer: Filter, body?: any) => any
+	getCustomTermQLst: (f: Term) => any
+	getPercentile: (term_id: string | number, percentile_lst: number[], filter?: Filter) => any
+	getterm: (f: any) => Term
+	getTerms: (f: any) => any
+	getTermdbConfig: () => any
+	getViolinPlotData: (args: any, _body?: any) => any
+	getAnnotatedSampleData: (args: any) => any
+	getDefaultBins: (args: any) => any
+	setTermBins(tw: TermWrapper): any
+	getTwMinCopy(tw: TermWrapper): any
+	uncacheTermQ: (term: Term, q: any) => any
+	hasVerifiedToken: () => boolean
+	tokenVerificationMessage: string
+	tokenVerificationPayload?: {
+		error?: string
+		linkKey?: string
+	}
+}