From a6276d56468be52d4a4af1369af88082fa0fe38e Mon Sep 17 00:00:00 2001 From: Steven Luscher Date: Tue, 4 Mar 2025 04:02:29 -0800 Subject: [PATCH] Document `@solana/functional` with TypeDoc (#165) Preview at https://delicate-gnome-f3ea81.netlify.app/modules --- packages/functional/README.md | 6 +- packages/functional/src/index.ts | 4 + packages/functional/src/pipe.ts | 154 ++++++++++++++++++++++++++++--- 3 files changed, 148 insertions(+), 16 deletions(-) diff --git a/packages/functional/README.md b/packages/functional/README.md index 944fd4048..1a6b7d811 100644 --- a/packages/functional/README.md +++ b/packages/functional/README.md @@ -17,7 +17,9 @@ This package contains generalized functional helpers and functional helpers spec ### `pipe()` -Until the [pipe operator](https://github.com/tc39/proposal-pipeline-operator) becomes part of JavaScript you can use this utility to create pipelines. +A pipeline is a solution that allows you to perform successive transforms of a value using functions. This is useful when building up a transaction message. + +Until the [pipeline operator](https://github.com/tc39/proposal-pipeline-operator) becomes part of JavaScript you can use this utility to create pipelines. ```ts const add = (a, b) => a + b; @@ -27,8 +29,6 @@ const sum = pipe(1, add10, add100); sum === 111; // true ``` -A pipeline is one solution to performing consecutive operations on a value using functions, such as you would when building a transaction. - ```ts const transferTransactionMessage = pipe( // The result of the first expression... diff --git a/packages/functional/src/index.ts b/packages/functional/src/index.ts index 9fa9aa15b..3c2207722 100644 --- a/packages/functional/src/index.ts +++ b/packages/functional/src/index.ts @@ -1 +1,5 @@ +/** + * This package contains generalized functional helpers and functional helpers specific to Solana application components. It can be used standalone, but it is also exported as part of Kit [`@solana/kit`](https://github.com/anza-xyz/kit/tree/main/packages/kit). + * @packageDocumentation + */ export * from './pipe'; diff --git a/packages/functional/src/pipe.ts b/packages/functional/src/pipe.ts index ab5f558da..7e2b0de10 100644 --- a/packages/functional/src/pipe.ts +++ b/packages/functional/src/pipe.ts @@ -1,14 +1,12 @@ /** - * General pipe function. - * Provide an initial value and a list of functions to pipe it through. + * A pipeline is a solution that allows you to perform successive transforms of a value using functions. This is useful when building up a transaction message. * - * Following common implementations of pipe functions that use TypeScript, - * this function supports a maximum arity of 10 for type safety. - * @see https://github.com/ramda/ramda/blob/master/source/pipe.js - * @see https://github.com/darky/rocket-pipes/blob/master/index.ts + * Until the [pipeline operator](https://github.com/tc39/proposal-pipeline-operator) becomes part of JavaScript you can use this utility to create pipelines. + * + * Following common implementations of pipe functions that use TypeScript, this function supports a maximum arity of 10 for type safety. * * Note you can use nested pipes to extend this limitation, like so: - * ```typescript + * ```ts * const myValue = pipe( * pipe( * 1, @@ -20,87 +18,217 @@ * (y) => y + 1, * ); * ``` - * @param init The initial value - * @param fns Any number of functions to pipe the value through - * @returns The final value with all functions applied + * + * @see https://github.com/ramda/ramda/blob/master/source/pipe.js + * @see https://github.com/darky/rocket-pipes/blob/master/index.ts + * + * @example Basic + * ```ts + * const add = (a, b) => a + b; + * const add10 = x => add(x, 10); + * const add100 = x => add(x, 100); + * const sum = pipe(1, add10, add100); + * sum === 111; // true + * ``` + * + * @example Building a Solana transaction message + * ```ts + * const transferTransactionMessage = pipe( + * // The result of the first expression... + * createTransactionMessage({ version: 0 }), + * // ...gets passed as the sole argument to the next function in the pipeline. + * tx => setTransactionMessageFeePayer(myAddress, tx), + * // The return value of that function gets passed to the next... + * tx => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, tx), + * // ...and so on. + * tx => appendTransactionMessageInstruction(createTransferInstruction(myAddress, toAddress, amountInLamports), tx), + * ); + * ``` + * + * @returns The initial value + */ +export function pipe( + /** The initial value */ + init: TInitial, +): TInitial; +/** + * @returns The return value of the final transform function + */ +export function pipe( + /** The initial value */ + init: TInitial, + /** The function with which to transform the initial value */ + init_r1: (init: TInitial) => R1, +): R1; +/** + * @returns The return value of the final transform function + */ +export function pipe( + /** The initial value */ + init: TInitial, + /** The function with which to transform the initial value */ + init_r1: (init: TInitial) => R1, + /** The function with which to transform the return value of the prior function */ + r1_r2: (r1: R1) => R2, +): R2; +/** + * @returns The return value of the final transform function */ -export function pipe(init: TInitial): TInitial; -export function pipe(init: TInitial, init_r1: (init: TInitial) => R1): R1; -export function pipe(init: TInitial, init_r1: (init: TInitial) => R1, r1_r2: (r1: R1) => R2): R2; export function pipe( + /** The initial value */ init: TInitial, + /** The function with which to transform the initial value */ init_r1: (init: TInitial) => R1, + /** The function with which to transform the return value of the prior function */ r1_r2: (r1: R1) => R2, + /** The function with which to transform the return value of the prior function */ r2_r3: (r2: R2) => R3, ): R3; +/** + * @returns The return value of the final transform function + */ export function pipe( + /** The initial value */ init: TInitial, + /** The function with which to transform the initial value */ init_r1: (init: TInitial) => R1, + /** The function with which to transform the return value of the prior function */ r1_r2: (r1: R1) => R2, + /** The function with which to transform the return value of the prior function */ r2_r3: (r2: R2) => R3, + /** The function with which to transform the return value of the prior function */ r3_r4: (r3: R3) => R4, ): R4; +/** + * @returns The return value of the final transform function + */ export function pipe( + /** The initial value */ init: TInitial, + /** The function with which to transform the initial value */ init_r1: (init: TInitial) => R1, + /** The function with which to transform the return value of the prior function */ r1_r2: (r1: R1) => R2, + /** The function with which to transform the return value of the prior function */ r2_r3: (r2: R2) => R3, + /** The function with which to transform the return value of the prior function */ r3_r4: (r3: R3) => R4, + /** The function with which to transform the return value of the prior function */ r4_r5: (r4: R4) => R5, ): R5; +/** + * @returns The return value of the final transform function + */ export function pipe( + /** The initial value */ init: TInitial, + /** The function with which to transform the initial value */ init_r1: (init: TInitial) => R1, + /** The function with which to transform the return value of the prior function */ r1_r2: (r1: R1) => R2, + /** The function with which to transform the return value of the prior function */ r2_r3: (r2: R2) => R3, + /** The function with which to transform the return value of the prior function */ r3_r4: (r3: R3) => R4, + /** The function with which to transform the return value of the prior function */ r4_r5: (r4: R4) => R5, + /** The function with which to transform the return value of the prior function */ r5_r6: (r5: R5) => R6, ): R6; +/** + * @returns The return value of the final transform function + */ export function pipe( + /** The initial value */ init: TInitial, + /** The function with which to transform the initial value */ init_r1: (init: TInitial) => R1, + /** The function with which to transform the return value of the prior function */ r1_r2: (r1: R1) => R2, + /** The function with which to transform the return value of the prior function */ r2_r3: (r2: R2) => R3, + /** The function with which to transform the return value of the prior function */ r3_r4: (r3: R3) => R4, + /** The function with which to transform the return value of the prior function */ r4_r5: (r4: R4) => R5, + /** The function with which to transform the return value of the prior function */ r5_r6: (r5: R5) => R6, + /** The function with which to transform the return value of the prior function */ r6_r7: (r6: R6) => R7, ): R7; +/** + * @returns The return value of the final transform function + */ export function pipe( + /** The initial value */ init: TInitial, + /** The function with which to transform the initial value */ init_r1: (init: TInitial) => R1, + /** The function with which to transform the return value of the prior function */ r1_r2: (r1: R1) => R2, + /** The function with which to transform the return value of the prior function */ r2_r3: (r2: R2) => R3, + /** The function with which to transform the return value of the prior function */ r3_r4: (r3: R3) => R4, + /** The function with which to transform the return value of the prior function */ r4_r5: (r4: R4) => R5, + /** The function with which to transform the return value of the prior function */ r5_r6: (r5: R5) => R6, + /** The function with which to transform the return value of the prior function */ r6_r7: (r6: R6) => R7, + /** The function with which to transform the return value of the prior function */ r7_r8: (r7: R7) => R8, ): R8; +/** + * @returns The return value of the final transform function + */ export function pipe( + /** The initial value */ init: TInitial, + /** The function with which to transform the initial value */ init_r1: (init: TInitial) => R1, + /** The function with which to transform the return value of the prior function */ r1_r2: (r1: R1) => R2, + /** The function with which to transform the return value of the prior function */ r2_r3: (r2: R2) => R3, + /** The function with which to transform the return value of the prior function */ r3_r4: (r3: R3) => R4, + /** The function with which to transform the return value of the prior function */ r4_r5: (r4: R4) => R5, + /** The function with which to transform the return value of the prior function */ r5_r6: (r5: R5) => R6, + /** The function with which to transform the return value of the prior function */ r6_r7: (r6: R6) => R7, + /** The function with which to transform the return value of the prior function */ r7_r8: (r7: R7) => R8, + /** The function with which to transform the return value of the prior function */ r8_r9: (r8: R8) => R9, ): R9; +/** + * @returns The return value of the final transform function + */ export function pipe( + /** The initial value */ init: TInitial, + /** The function with which to transform the initial value */ init_r1: (init: TInitial) => R1, + /** The function with which to transform the return value of the prior function */ r1_r2: (r1: R1) => R2, + /** The function with which to transform the return value of the prior function */ r2_r3: (r2: R2) => R3, + /** The function with which to transform the return value of the prior function */ r3_r4: (r3: R3) => R4, + /** The function with which to transform the return value of the prior function */ r4_r5: (r4: R4) => R5, + /** The function with which to transform the return value of the prior function */ r5_r6: (r5: R5) => R6, + /** The function with which to transform the return value of the prior function */ r6_r7: (r6: R6) => R7, + /** The function with which to transform the return value of the prior function */ r7_r8: (r7: R7) => R8, + /** The function with which to transform the return value of the prior function */ r8_r9: (r8: R8) => R9, + /** The function with which to transform the return value of the prior function */ r9_r10: (r9: R9) => R10, ): R10; export function pipe(init: TInitial, ...fns: CallableFunction[]) {