@xyd-js/sources 0.0.1-xyd.0

package/example/package-b/src/billing.ts

@@ -0,0 +1,193 @@
+/**
+ *
+ * Includes enums for payment methods and transaction statuses, interfaces for billing transactions and receipts,
+ * and services to process transactions, manage billing history, and generate receipts.
+ *
+ * This module ensures comprehensive handling of billing data and operations, facilitating integrations with various payment providers and internal systems. It serves as a foundation for the financial transaction processing system, providing traceability and accountability through structured data and services.
+ *
+ * @module
+ */
+
+/**
+ * Enum representing different types of payment methods.
+ * These are used to specify the payment mechanism chosen by a customer.
+ */
+export enum PaymentMethod {
+    /** Payment through credit card. */
+    CreditCard = "Credit Card",
+
+    /** Payment through PayPal. Ideal for users who prefer not to directly use their credit card details. */
+    PayPal = "PayPal",
+
+    /** Payment via direct bank transfer. Used typically for larger transactions or where credit cards and PayPal are not viable. */
+    BankTransfer = "Bank Transfer",
+}
+
+/**
+ * Enum representing different transaction statuses.
+ * These statuses indicate the current state of a billing transaction in the process pipeline.
+ */
+export enum TransactionStatus {
+    /** Transaction has been initiated but not yet processed. */
+    Pending = "Pending",
+
+    /** Transaction has been successfully processed. */
+    Completed = "Completed",
+
+    /** Transaction failed due to an error or rejection. */
+    Failed = "Failed",
+}
+
+/**
+ * Interface representing a billing transaction.
+ * This structure encapsulates all key details of a financial transaction within the system.
+ */
+export interface BillingTransaction {
+    /**
+     * Unique identifier for the transaction. This ID is used to track and reference the transaction
+     * throughout the billing process.
+     */
+    transactionId: string;
+
+    /**
+     * Identifier for the order associated with this transaction. Helps link the transaction to specific goods or services purchased.
+     */
+    orderId: string;
+
+    /**
+     * The total amount of money involved in the transaction. This is usually in the smallest unit of the currency,
+     * such as cents in USD.
+     */
+    amount: number;
+
+    /**
+     * The method of payment used for the transaction, as defined by the PaymentMethod enum.
+     * This indicates how the customer chose to pay (e.g., Credit Card, PayPal, Bank Transfer).
+     */
+    paymentMethod: PaymentMethod;
+
+    /**
+     * The current status of the transaction, categorized by the TransactionStatus enum. Indicates whether the
+     * transaction is pending, completed, or has failed.
+     */
+    status: TransactionStatus;
+}
+
+/**
+ * Interface representing a billing receipt.
+ * Provides a record of the transaction for both the customer and the business.
+ */
+export interface BillingReceipt {
+    /**
+     * Unique identifier for the receipt. This ID is crucial for referencing and tracking the receipt
+     * in financial records and customer queries.
+     */
+    receiptId: string;
+
+    /**
+     * The transaction details associated with this receipt. Links the receipt to the actual transaction
+     * that took place.
+     */
+    transaction: BillingTransaction;
+
+    /**
+     * The timestamp (in UNIX epoch time) when the receipt was generated. Provides a precise record of when
+     * the transaction was finalized and acknowledged.
+     */
+    timestamp: number;
+}
+
+/**
+ * Service for managing billing transactions.
+ * Provides functionality to process and retrieve billing transactions.
+ * @class
+ */
+export class BillingService {
+    /** Holds all processed transactions within the service. */
+    private transactions: BillingTransaction[] = [];
+
+    /**
+     * Processes a billing transaction by adding it to the list of transactions.
+     * This simulates the transaction execution and storage in a production environment.
+     * @param transaction - The billing transaction to be processed.
+     * @returns The processed billing transaction, now stored in the service.
+     */
+    processTransaction(transaction: BillingTransaction): BillingTransaction {
+        this.transactions.push(transaction);
+        return transaction;
+    }
+
+    /**
+     * Retrieves all the billing transactions that have been processed.
+     * Useful for audits and general transaction management.
+     * @returns An array of all billing transactions.
+     */
+    getAllTransactions(): BillingTransaction[] {
+        return this.transactions;
+    }
+}
+
+/**
+ * Service for managing billing history.
+ * Provides functionality to store and retrieve the history of transactions.
+ * @class
+ */
+export class BillingHistoryService {
+    /** Holds all transactions that have been added to the billing history. */
+    private history: BillingTransaction[] = [];
+
+    /**
+     * Adds a transaction to the billing history.
+     * This method is typically called after a transaction is completed to maintain a record.
+     * @param transaction - The billing transaction to be added to the history.
+     */
+    addTransactionToHistory(transaction: BillingTransaction): void {
+        this.history.push(transaction);
+    }
+
+    /**
+     * Retrieves the complete billing history, providing access to all transactions that have been recorded.
+     * This is useful for historical analysis and auditing purposes.
+     * @returns An array of all billing transactions in the history.
+     */
+    getBillingHistory(): BillingTransaction[] {
+        return this.history;
+    }
+}
+
+/**
+ * Service for generating billing receipts.
+ * Provides functionality to generate and retrieve receipts for transactions.
+ * @class
+ */
+export class BillingReceiptService {
+    /**
+     * Stores all receipts generated for transactions.
+     */
+    public receipts: BillingReceipt[] = [];
+
+    /**
+     * Generates a billing receipt for a transaction and stores it.
+     * Each receipt includes a unique ID and timestamp, essential for record-keeping and customer service.
+     * @param transaction - The billing transaction for which to generate a receipt.
+     * @returns The generated billing receipt.
+     */
+    generateReceipt(transaction: BillingTransaction): BillingReceipt {
+        const receipt: BillingReceipt = {
+            receiptId: `receipt_${Date.now()}`,
+            transaction,
+            timestamp: Date.now(),
+        };
+        this.receipts.push(receipt);
+        return receipt;
+    }
+
+    /**
+     * Retrieves all the billing receipts that have been generated.
+     * Useful for providing customers with copies of their receipts or for internal financial tracking.
+     * @returns An array of all billing receipts.
+     */
+    getAllReceipts(): BillingReceipt[] {
+        return this.receipts;
+    }
+}

package/example/package-b/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./billing"
+
+/**
+ * Returns a message builder message.
+ */
+export function messageBuilder(): string {
+    return 'Hello world!';
+}

package/example/package-b/tsconfig.json

@@ -0,0 +1,20 @@
+{
+  "compilerOptions": {
+    "target": "ES2020",
+    "module": "ESNext",
+    "moduleResolution": "bundler",
+    "strict": true,
+    "esModuleInterop": true,
+    "skipLibCheck": true,
+    "forceConsistentCasingInFileNames": true,
+    "outDir": "./dist",
+    "declaration": true,
+    "declarationMap": true,
+    "incremental": true,
+    "tsBuildInfoFile": "./dist/tsconfig.tsbuildinfo"
+  },
+  "include": [
+    "src/**/*.ts"
+  ],
+  "exclude": ["node_modules", "dist"]
+}

package/package.json

@@ -0,0 +1,22 @@
+{
+  "name": "@xyd-js/sources",
+  "version": "0.0.1-xyd.0",
+  "description": "",
+  "main": "./dist/index.js",
+  "type": "module",
+  "dependencies": {
+    "typedoc": "^0.28.1"
+  },
+  "peerDependencies": {
+    "@xyd-js/uniform": "0.1.0-xyd.11"
+  },
+  "devDependencies": {
+    "rimraf": "^3.0.2",
+    "tsup": "^8.3.0"
+  },
+  "scripts": {
+    "clean": "rimraf build",
+    "prebuild": "pnpm clean",
+    "build": "tsup"
+  }
+}

package/references_todo.json

@@ -0,0 +1,220 @@
+[
+  {
+    "title": "Class ExampleClass",
+    "canonical": "class-ExampleClass",
+    "description": "---\ntitle: ExampleClass \ngroup: [Source Code, Classes]\n---\nReturns a personalized hello world message.\n",
+    "context": {
+      "fileName": "index.ts",
+      "fileFullPath": "src/index.ts",
+      "line": 32,
+      "col": 13,
+      "signatureText": {
+        "code": "export class ExampleClass {\n}",
+        "lang": "ts"
+      },
+      "sourcecode": {
+        "code": "export class ExampleClass {\n    /**\n     * Returns a hello world message.\n     */\n    helloWorld(): string {\n        return 'Hello world!';\n    }\n}",
+        "lang": "ts"
+      },
+      "package": "@xyd-sources-examples/package-a"
+    },
+    "examples": {
+      "groups": []
+    },
+    "definitions": [
+      {
+        "title": "Constructor",
+        "properties": []
+      },
+      {
+        "title": "Methods",
+        "properties": [
+          {
+            "name": "helloWorld",
+            "type": "string",
+            "description": "Returns a hello world message.\n"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "title": "Function gqlSchemaToReferences",
+    "canonical": "fn-gqlSchemaToReferences",
+    "description": "---\ntitle: gqlSchemaToReferences\nabc: 123\ngroup: [Sourc, Functions]\n---\nConverts a GraphQL schema file to references.\n",
+    "context": {
+      "fileName": "index.ts",
+      "fileFullPath": "src/index.ts",
+      "line": 48,
+      "col": 16,
+      "signatureText": {
+        "code": "export function gqlSchemaToReferences(schemaLocation: string): Promise<[\n]>;",
+        "lang": "ts"
+      },
+      "sourcecode": {
+        "code": "export function gqlSchemaToReferences(\n    schemaLocation: string\n): Promise<[]> {\n    if (schemaLocation.endsWith(\".graphql\")) {\n        return Promise.resolve([])\n    }\n\n    return Promise.resolve([])\n}",
+        "lang": "ts"
+      },
+      "package": "@xyd-sources-examples/package-a"
+    },
+    "examples": {
+      "groups": []
+    },
+    "definitions": [
+      {
+        "title": "Returns",
+        "properties": [
+          {
+            "name": "",
+            "type": "<Promise>",
+            "description": "references\n"
+          }
+        ]
+      },
+      {
+        "title": "Parameters",
+        "properties": [
+          {
+            "name": "schemaLocation",
+            "type": "string",
+            "description": "The location of the schema file.\n"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "title": "Function helloWorld",
+    "canonical": "fn-helloWorld",
+    "description": "---\ntitle: helloWorld\nabc: 123\ngroup: [Sourc, Functions]\n---\nReturns a hello world message.\n",
+    "context": {
+      "fileName": "index.ts",
+      "fileFullPath": "src/index.ts",
+      "line": 4,
+      "col": 16,
+      "signatureText": {
+        "code": "export function helloWorld(): string;",
+        "lang": "ts"
+      },
+      "sourcecode": {
+        "code": "export function helloWorld(): string {\n    return 'Hello world!';\n}",
+        "lang": "ts"
+      },
+      "package": "@xyd-sources-examples/package-a"
+    },
+    "examples": {
+      "groups": []
+    },
+    "definitions": [
+      {
+        "title": "Returns",
+        "properties": [
+          {
+            "name": "",
+            "type": "string",
+            "description": ""
+          }
+        ]
+      },
+      {
+        "title": "Parameters",
+        "properties": []
+      }
+    ]
+  },
+  {
+    "title": "Function helloWorldV2",
+    "canonical": "fn-helloWorldV2",
+    "description": "---\ntitle: helloWorldV2\nabc: 123\ngroup: [Sourc, Functions]\n---\nReturns a personalized hello world message.\n",
+    "context": {
+      "fileName": "index.ts",
+      "fileFullPath": "src/index.ts",
+      "line": 15,
+      "col": 16,
+      "signatureText": {
+        "code": "export function helloWorldV2(name: string, enthusiastic: boolean = false): string;",
+        "lang": "ts"
+      },
+      "sourcecode": {
+        "code": "export function helloWorldV2(name: string, enthusiastic: boolean = false): string {\n    return enthusiastic ? `Hello, ${name}!` : `Hello, ${name}`;\n}",
+        "lang": "ts"
+      },
+      "package": "@xyd-sources-examples/package-a"
+    },
+    "examples": {
+      "groups": []
+    },
+    "definitions": [
+      {
+        "title": "Returns",
+        "properties": [
+          {
+            "name": "",
+            "type": "string",
+            "description": "A greeting message string.\n"
+          }
+        ]
+      },
+      {
+        "title": "Parameters",
+        "properties": [
+          {
+            "name": "name",
+            "type": "string",
+            "description": "Name of the person to greet.\n"
+          },
+          {
+            "name": "enthusiastic",
+            "type": "boolean",
+            "description": "If true, adds an exclamation point to the greeting.\n"
+          }
+        ]
+      }
+    ]
+  },
+  {
+    "title": "Function helloWorldV3",
+    "canonical": "fn-helloWorldV3",
+    "description": "---\ntitle: helloWorldV3\nabc: 123\ngroup: [Sourc, Functions]\n---\nReturns a personalized hello world message.\n",
+    "context": {
+      "fileName": "index.ts",
+      "fileFullPath": "src/index.ts",
+      "line": 25,
+      "col": 16,
+      "signatureText": {
+        "code": "export function helloWorldV3<T>(name: T): string;",
+        "lang": "ts"
+      },
+      "sourcecode": {
+        "code": "export function helloWorldV3<T>(name: T): string {\n    return `Hello, ${name}!`\n}",
+        "lang": "ts"
+      },
+      "package": "@xyd-sources-examples/package-a"
+    },
+    "examples": {
+      "groups": []
+    },
+    "definitions": [
+      {
+        "title": "Returns",
+        "properties": [
+          {
+            "name": "",
+            "type": "string",
+            "description": "A greeting message string.\n"
+          }
+        ]
+      },
+      {
+        "title": "Parameters",
+        "properties": [
+          {
+            "name": "name",
+            "type": "<T>",
+            "description": "Name of the person to greet.\n"
+          }
+        ]
+      }
+    ]
+  }
+]

package/src/SignatureText.ts

@@ -0,0 +1,214 @@
+import * as ts from 'typescript';
+import * as fs from "node:fs";
+
+// TODO: in the future more lightweight solution ??? - currently it's fine cuz it uses battle-tested TypeScript API
+
+const printer = ts.createPrinter({removeComments: true});
+
+export class SignatureTextLoader {
+    protected sourceFile: ts.SourceFile;
+
+    constructor(sourcePath: string) {
+        const source = fs.readFileSync(sourcePath, 'utf-8');
+
+        this.sourceFile = ts.createSourceFile(
+            sourcePath,
+            source,
+            ts.ScriptTarget.Latest,
+            true
+        );
+    }
+}
+
+export class MultiSignatureLoader {
+    private loaders: Map<string, SignatureTextLoader>
+
+    constructor() {
+        this.loaders = new Map<string, SignatureTextLoader>()
+    }
+
+    protected load(path: string) {
+        if (this.loaders.has(path)) {
+            return this.loaders.get(path)
+        }
+
+        const loader = new SignatureTextLoader(path)
+        this.loaders.set(path, loader)
+
+        return loader
+    }
+}
+
+/**
+ * Get the signature text of a function, class, interface, enum, or type alias at a specific line.
+ *
+ * @param sign - instance of SignatureText
+ * @param targetLine - the line number of the signature in source code
+ *
+ * @returns code friendly signature text
+ */
+export function signatureTextByLine(
+    sign: SignatureTextLoader,
+    targetLine: number
+) {
+    return signatureText.call(sign, targetLine)
+}
+
+/**
+ * Get the source code of a function, class, interface, enum, or type alias at a specific line.
+ *
+ * @param sign - instance of SignatureText
+ * @param targetLine - the line number of the signature in source code
+ *
+ * @returns source code of the signature
+*/
+export function signatureSourceCodeByLine(
+    sign: SignatureTextLoader,
+    targetLine: number
+) {
+    return signatureSourceCode.call(sign, targetLine)
+}
+
+function signatureText(
+    this: SignatureTextLoader,
+    targetLine: number
+) {
+    const sourceFile = this.sourceFile;
+    const signatureNode = findSignatureNode.call(
+        this,
+        sourceFile,
+        [targetLine]
+    );
+
+    if (!signatureNode) {
+        console.error("(signatureText): `signatureNode` is empty, something went wrong");
+        return
+    }
+
+    const printableSignatureNode = nodeToPrintableSignatureNode(signatureNode);
+    if (!printableSignatureNode) {
+        console.error("(signatureText): cannot convert `signatureNode` to `printableSignatureNode`");
+        return
+    }
+
+    return printer.printNode(ts.EmitHint.Unspecified, printableSignatureNode, sourceFile).trim()
+
+}
+
+// TODO: this function is probably not optimized well (recursion when not needed)
+function findSignatureNode(
+    this: SignatureTextLoader,
+    node: ts.Node,
+    targetLines: number[]
+) {
+    let isSourceFile = false
+    if (node === node.getSourceFile()) {
+        isSourceFile = true
+    }
+
+    if (!isSourceFile && isNodeAtLine(node, targetLines, this.sourceFile)) {
+        return node
+    }
+
+    let signatureNode: ts.Node | undefined;
+
+    ts.forEachChild(node, (n) => {
+        if (signatureNode) {
+            return
+        }
+        signatureNode = findSignatureNode.call(this, n, targetLines)
+    });
+
+    return signatureNode
+}
+
+
+function signatureSourceCode(
+    this: SignatureTextLoader,
+    targetLine: number
+) {
+    const sourceFile = this.sourceFile;
+    const signatureNode = findSignatureNode.call(
+        this,
+        sourceFile,
+        [targetLine]
+    );
+
+    if (!signatureNode) {
+        console.error("(signatureSourceCode): `signatureNode` is empty, something went wrong");
+        return
+    }
+
+    // Get the start and end positions of the node
+    const start = signatureNode.getStart(sourceFile);
+    const end = signatureNode.getEnd();
+
+    // Get the source text between start and end
+    return sourceFile.text.substring(start, end).trim();
+}
+
+function nodeToPrintableSignatureNode(node: ts.Node) {
+    let resp: ts.Node | undefined;
+
+    if (ts.isFunctionDeclaration(node)) {
+        resp = ts.factory.updateFunctionDeclaration(
+            node,
+            node.modifiers,
+            node.asteriskToken,
+            node.name,
+            node.typeParameters,
+            node.parameters,
+            node.type,
+            undefined
+        );
+    } else if (ts.isClassDeclaration(node)) {
+        resp = ts.factory.updateClassDeclaration(
+            node,
+            node.modifiers,
+            node.name,
+            node.typeParameters,
+            node.heritageClauses,
+            []
+        );
+    } else if (ts.isInterfaceDeclaration(node)) {
+        resp = ts.factory.updateInterfaceDeclaration(
+            node,
+            node.modifiers,
+            node.name,
+            node.typeParameters,
+            node.heritageClauses,
+            []
+        );
+    } else if (ts.isEnumDeclaration(node)) {
+        resp = ts.factory.updateEnumDeclaration(
+            node,
+            node.modifiers,
+            node.name,
+            []
+        );
+    } else if (ts.isTypeAliasDeclaration(node)) {
+        resp = ts.factory.updateTypeAliasDeclaration(
+            node,
+            node.modifiers,
+            node.name,
+            node.typeParameters,
+            node.type
+        );
+    }
+
+    if (!resp) {
+        console.error("(nodeToPrintableSignatureNode): resp is empty, something went wrong");
+        return;
+    }
+
+    return resp
+}
+
+function isNodeAtLine(node: ts.Node, lines: number[], sf: ts.SourceFile): boolean {
+    const {line: startLine} = sf.getLineAndCharacterOfPosition(node.getStart());
+
+    return lines.includes(startLine + 1); // lines are 0-based internally
+}
+
+
+