From 17bd7ab42d8d2b88599d3e9f13129035798a16e2 Mon Sep 17 00:00:00 2001 From: David Snelling Date: Thu, 31 Jul 2025 14:24:16 -0700 Subject: [PATCH] **feat(utils): add type utility functions and examples for runtime type management** - Introduced `getNounTypes`, `getVerbTypes`, `getNounTypeMap`, and `getVerbTypeMap` utilities for managing noun and verb types at runtime. - Added comprehensive unit tests (`type-utils.test.ts`) to ensure correctness of type utility functions. - Created new example files (`type-utils-example.js`, `type-utils-example.ts`) to demonstrate the use of type utilities in JavaScript and TypeScript environments. - Updated `README.md` with detailed documentation and usage examples for the new type utilities. - Enhanced `index.ts` to export the new utility functions, making them accessible throughout the library. **Purpose**: Facilitate easy access, validation, and manipulation of noun and verb types in client applications, providing better runtime type management. --- README.md | 39 ++++++++++++ examples/type-utils-example.js | 95 ++++++++++++++++++++++++++++ examples/type-utils-example.ts | 109 +++++++++++++++++++++++++++++++++ src/index.ts | 12 +++- src/utils/typeUtils.ts | 44 +++++++++++++ tests/type-utils.test.ts | 94 ++++++++++++++++++++++++++++ 6 files changed, 392 insertions(+), 1 deletion(-) create mode 100644 examples/type-utils-example.js create mode 100644 examples/type-utils-example.ts create mode 100644 src/utils/typeUtils.ts create mode 100644 tests/type-utils.test.ts diff --git a/README.md b/README.md index 6fef66ea..6044df52 100644 --- a/README.md +++ b/README.md @@ -399,6 +399,45 @@ Connections between nouns (edges in the graph): - Verbs have types that define the relationship (RelatedTo, Controls, Contains, etc.) - Verbs can have their own metadata to describe the relationship +### Type Utilities + +Brainy provides utility functions to access lists of noun and verb types: + +```typescript +import { + NounType, + VerbType, + getNounTypes, + getVerbTypes, + getNounTypeMap, + getVerbTypeMap +} from '@soulcraft/brainy' + +// At development time: +// Access specific types directly from the NounType and VerbType objects +console.log(NounType.Person) // 'person' +console.log(VerbType.Contains) // 'contains' + +// At runtime: +// Get a list of all noun types +const nounTypes = getNounTypes() // ['person', 'organization', 'location', ...] + +// Get a list of all verb types +const verbTypes = getVerbTypes() // ['relatedTo', 'contains', 'partOf', ...] + +// Get a map of noun type keys to values +const nounTypeMap = getNounTypeMap() // { Person: 'person', Organization: 'organization', ... } + +// Get a map of verb type keys to values +const verbTypeMap = getVerbTypeMap() // { RelatedTo: 'relatedTo', Contains: 'contains', ... } +``` + +These utility functions make it easy to: +- Get a complete list of available noun and verb types +- Validate user input against valid types +- Create dynamic UI components that display or select from available types +- Map between type keys and their string values + ## Command Line Interface Brainy includes a powerful CLI for managing your data. The CLI is available as a separate package diff --git a/examples/type-utils-example.js b/examples/type-utils-example.js new file mode 100644 index 00000000..9423b7de --- /dev/null +++ b/examples/type-utils-example.js @@ -0,0 +1,95 @@ +/** + * Type Utilities Example + * + * This example demonstrates how to use the Brainy library's type utility functions + * to access lists of noun and verb types at runtime. + */ + +/* eslint-disable no-console */ + +// Import the Brainy library +import { + NounType, + VerbType, + getNounTypes, + getVerbTypes, + getNounTypeMap, + getVerbTypeMap +} from '@soulcraft/brainy' + +// Example 1: Get a list of all noun types +console.log('=== All Noun Types ===') +const nounTypes = getNounTypes() +console.log(nounTypes) +console.log(`Total noun types: ${nounTypes.length}`) +console.log('\n') + +// Example 2: Get a list of all verb types +console.log('=== All Verb Types ===') +const verbTypes = getVerbTypes() +console.log(verbTypes) +console.log(`Total verb types: ${verbTypes.length}`) +console.log('\n') + +// Example 3: Get a map of noun type keys to values +console.log('=== Noun Type Map ===') +const nounTypeMap = getNounTypeMap() +console.log(nounTypeMap) +console.log('\n') + +// Example 4: Get a map of verb type keys to values +console.log('=== Verb Type Map ===') +const verbTypeMap = getVerbTypeMap() +console.log(verbTypeMap) +console.log('\n') + +// Example 5: Using specific noun types +console.log('=== Using Specific Noun Types ===') +console.log(`Person noun type: ${NounType.Person}`) +console.log(`Organization noun type: ${NounType.Organization}`) +console.log(`Location noun type: ${NounType.Location}`) +console.log('\n') + +// Example 6: Using specific verb types +console.log('=== Using Specific Verb Types ===') +console.log(`RelatedTo verb type: ${VerbType.RelatedTo}`) +console.log(`Contains verb type: ${VerbType.Contains}`) +console.log(`PartOf verb type: ${VerbType.PartOf}`) +console.log('\n') + +// Example 7: Checking if a value is a valid noun type +console.log('=== Checking Valid Noun Types ===') +const isValidNounType = (value) => nounTypes.includes(value) +console.log(`Is 'person' a valid noun type? ${isValidNounType('person')}`) +console.log(`Is 'invalid' a valid noun type? ${isValidNounType('invalid')}`) +console.log('\n') + +// Example 8: Checking if a value is a valid verb type +console.log('=== Checking Valid Verb Types ===') +const isValidVerbType = (value) => verbTypes.includes(value) +console.log(`Is 'contains' a valid verb type? ${isValidVerbType('contains')}`) +console.log(`Is 'invalid' a valid verb type? ${isValidVerbType('invalid')}`) +console.log('\n') + +// Example 9: Getting the key for a noun type value +console.log('=== Getting Noun Type Keys ===') +const getNounTypeKey = (value) => { + for (const [key, val] of Object.entries(nounTypeMap)) { + if (val === value) return key + } + return null +} +console.log(`Key for 'person' noun type: ${getNounTypeKey('person')}`) +console.log(`Key for 'organization' noun type: ${getNounTypeKey('organization')}`) +console.log('\n') + +// Example 10: Getting the key for a verb type value +console.log('=== Getting Verb Type Keys ===') +const getVerbTypeKey = (value) => { + for (const [key, val] of Object.entries(verbTypeMap)) { + if (val === value) return key + } + return null +} +console.log(`Key for 'contains' verb type: ${getVerbTypeKey('contains')}`) +console.log(`Key for 'partOf' verb type: ${getVerbTypeKey('partOf')}`) diff --git a/examples/type-utils-example.ts b/examples/type-utils-example.ts new file mode 100644 index 00000000..ef23ba05 --- /dev/null +++ b/examples/type-utils-example.ts @@ -0,0 +1,109 @@ +/** + * Type Utilities Example + * + * This example demonstrates how to use the Brainy library's type utility functions + * to access lists of noun and verb types at runtime. + */ + +import { + NounType, + VerbType, + getNounTypes, + getVerbTypes, + getNounTypeMap, + getVerbTypeMap +} from '@soulcraft/brainy' + +/** + * Example function that demonstrates how to get and use noun types + */ +function demonstrateNounTypes(): void { + // Get a list of all noun types + console.log('=== All Noun Types ===') + const nounTypes = getNounTypes() + console.log(nounTypes) + console.log(`Total noun types: ${nounTypes.length}`) + + // Get a map of noun type keys to values + console.log('\n=== Noun Type Map ===') + const nounTypeMap = getNounTypeMap() + console.log(nounTypeMap) + + // Using specific noun types + console.log('\n=== Using Specific Noun Types ===') + console.log(`Person noun type: ${NounType.Person}`) + console.log(`Organization noun type: ${NounType.Organization}`) + console.log(`Location noun type: ${NounType.Location}`) + + // Checking if a value is a valid noun type + console.log('\n=== Checking Valid Noun Types ===') + const isValidNounType = (value: string): boolean => nounTypes.includes(value) + console.log(`Is 'person' a valid noun type? ${isValidNounType('person')}`) + console.log(`Is 'invalid' a valid noun type? ${isValidNounType('invalid')}`) + + // Getting the key for a noun type value + console.log('\n=== Getting Noun Type Keys ===') + const getNounTypeKey = (value: string): string | null => { + for (const [key, val] of Object.entries(nounTypeMap)) { + if (val === value) return key + } + return null + } + console.log(`Key for 'person' noun type: ${getNounTypeKey('person')}`) + console.log(`Key for 'organization' noun type: ${getNounTypeKey('organization')}`) +} + +/** + * Example function that demonstrates how to get and use verb types + */ +function demonstrateVerbTypes(): void { + // Get a list of all verb types + console.log('\n=== All Verb Types ===') + const verbTypes = getVerbTypes() + console.log(verbTypes) + console.log(`Total verb types: ${verbTypes.length}`) + + // Get a map of verb type keys to values + console.log('\n=== Verb Type Map ===') + const verbTypeMap = getVerbTypeMap() + console.log(verbTypeMap) + + // Using specific verb types + console.log('\n=== Using Specific Verb Types ===') + console.log(`RelatedTo verb type: ${VerbType.RelatedTo}`) + console.log(`Contains verb type: ${VerbType.Contains}`) + console.log(`PartOf verb type: ${VerbType.PartOf}`) + + // Checking if a value is a valid verb type + console.log('\n=== Checking Valid Verb Types ===') + const isValidVerbType = (value: string): boolean => verbTypes.includes(value) + console.log(`Is 'contains' a valid verb type? ${isValidVerbType('contains')}`) + console.log(`Is 'invalid' a valid verb type? ${isValidVerbType('invalid')}`) + + // Getting the key for a verb type value + console.log('\n=== Getting Verb Type Keys ===') + const getVerbTypeKey = (value: string): string | null => { + for (const [key, val] of Object.entries(verbTypeMap)) { + if (val === value) return key + } + return null + } + console.log(`Key for 'contains' verb type: ${getVerbTypeKey('contains')}`) + console.log(`Key for 'partOf' verb type: ${getVerbTypeKey('partOf')}`) +} + +/** + * Main function to run the example + */ +function main(): void { + console.log('BRAINY TYPE UTILITIES EXAMPLE') + console.log('=============================') + + demonstrateNounTypes() + demonstrateVerbTypes() + + console.log('\nExample completed!') +} + +// Run the example +main() diff --git a/src/index.ts b/src/index.ts index eb6bfdc6..29b8fe84 100644 --- a/src/index.ts +++ b/src/index.ts @@ -378,7 +378,17 @@ export type { Currency, Measurement } -export { NounType, VerbType } +// Export type utility functions +import { getNounTypes, getVerbTypes, getNounTypeMap, getVerbTypeMap } from './utils/typeUtils.js' + +export { + NounType, + VerbType, + getNounTypes, + getVerbTypes, + getNounTypeMap, + getVerbTypeMap +} // Export MCP (Model Control Protocol) components import { diff --git a/src/utils/typeUtils.ts b/src/utils/typeUtils.ts new file mode 100644 index 00000000..38f1bd2a --- /dev/null +++ b/src/utils/typeUtils.ts @@ -0,0 +1,44 @@ +/** + * Type Utilities + * + * This module provides utility functions for working with the Brainy type system, + * particularly for accessing lists of noun and verb types. + */ + +import { NounType, VerbType } from '../types/graphTypes.js' + +/** + * Returns an array of all available noun types + * + * @returns {string[]} Array of all noun type values + */ +export function getNounTypes(): string[] { + return Object.values(NounType) +} + +/** + * Returns an array of all available verb types + * + * @returns {string[]} Array of all verb type values + */ +export function getVerbTypes(): string[] { + return Object.values(VerbType) +} + +/** + * Returns a map of noun type keys to their string values + * + * @returns {Record} Map of noun type keys to values + */ +export function getNounTypeMap(): Record { + return { ...NounType } +} + +/** + * Returns a map of verb type keys to their string values + * + * @returns {Record} Map of verb type keys to values + */ +export function getVerbTypeMap(): Record { + return { ...VerbType } +} diff --git a/tests/type-utils.test.ts b/tests/type-utils.test.ts new file mode 100644 index 00000000..1ac67eb0 --- /dev/null +++ b/tests/type-utils.test.ts @@ -0,0 +1,94 @@ +/** + * Tests for type utility functions + * + * This test file verifies that the utility functions for accessing noun and verb types + * work correctly and return the expected values. + */ + +import { describe, it, expect } from 'vitest' +import { + NounType, + VerbType, + getNounTypes, + getVerbTypes, + getNounTypeMap, + getVerbTypeMap +} from '../src/index.js' + +describe('Type Utility Functions', () => { + describe('getNounTypes', () => { + it('should return an array of all noun types', () => { + const nounTypes = getNounTypes() + + // Check that the result is an array + expect(Array.isArray(nounTypes)).toBe(true) + + // Check that it contains all the expected values + expect(nounTypes).toContain(NounType.Person) + expect(nounTypes).toContain(NounType.Organization) + expect(nounTypes).toContain(NounType.Location) + expect(nounTypes).toContain(NounType.Thing) + expect(nounTypes).toContain(NounType.Concept) + + // Check that the length matches the number of properties in NounType + expect(nounTypes.length).toBe(Object.keys(NounType).length) + }) + }) + + describe('getVerbTypes', () => { + it('should return an array of all verb types', () => { + const verbTypes = getVerbTypes() + + // Check that the result is an array + expect(Array.isArray(verbTypes)).toBe(true) + + // Check that it contains some expected values + expect(verbTypes).toContain(VerbType.RelatedTo) + expect(verbTypes).toContain(VerbType.Contains) + expect(verbTypes).toContain(VerbType.PartOf) + expect(verbTypes).toContain(VerbType.LocatedAt) + expect(verbTypes).toContain(VerbType.References) + + // Check that the length matches the number of properties in VerbType + expect(verbTypes.length).toBe(Object.keys(VerbType).length) + }) + }) + + describe('getNounTypeMap', () => { + it('should return a map of all noun type keys to values', () => { + const nounTypeMap = getNounTypeMap() + + // Check that the result is an object + expect(typeof nounTypeMap).toBe('object') + + // Check that it contains all the expected keys and values + expect(nounTypeMap.Person).toBe(NounType.Person) + expect(nounTypeMap.Organization).toBe(NounType.Organization) + expect(nounTypeMap.Location).toBe(NounType.Location) + expect(nounTypeMap.Thing).toBe(NounType.Thing) + expect(nounTypeMap.Concept).toBe(NounType.Concept) + + // Check that the number of keys matches the number of properties in NounType + expect(Object.keys(nounTypeMap).length).toBe(Object.keys(NounType).length) + }) + }) + + describe('getVerbTypeMap', () => { + it('should return a map of all verb type keys to values', () => { + const verbTypeMap = getVerbTypeMap() + + // Check that the result is an object + expect(typeof verbTypeMap).toBe('object') + + // Check that it contains all the expected keys and values + expect(verbTypeMap.RelatedTo).toBe(VerbType.RelatedTo) + expect(verbTypeMap.Contains).toBe(VerbType.Contains) + expect(verbTypeMap.PartOf).toBe(VerbType.PartOf) + expect(verbTypeMap.LocatedAt).toBe(VerbType.LocatedAt) + expect(verbTypeMap.References).toBe(VerbType.References) + + // Check that the number of keys matches the number of properties in VerbType + expect(Object.keys(verbTypeMap).length).toBe(Object.keys(VerbType).length) + }) + }) +})