mftsccs-browser

A comprehensive TypeScript/JavaScript package for managing concepts, connections, and compositions in a knowledge graph structure.

Table of Contents

• Overview
• Features
• Installation
• Quick Start
• Core Concepts
• Documentation
• API Overview
• Configuration
• Examples
• Development
• Publishing to npm
• Contributing
• License

Overview

mftsccs-browser is a powerful browser-based data management library that implements a sophisticated Concept & Connection System (TSCCS). It provides a flexible way to model, store, and query knowledge graphs with support for both online and offline operations.

📚 Fully Documented

Every function, class, and method is documented with concise JSDoc comments - making it easy for developers to understand and use the package. Hover over any function in your IDE to see parameter types, descriptions, examples, and return values.

What is it for?

• Building knowledge graphs and semantic networks
• Managing complex relational data in browser applications
• Creating applications that need offline-first data management
• Implementing concept-based search and discovery systems
• Building applications with hierarchical and networked data structures

Features

Core Data Management

• Concept & Connection Management: Create and manage entities (concepts) and their relationships (connections)
  • Simplified Connection API ⭐: CreateConnection() auto-creates type concepts, saving developer time
• Composition System: Build complex hierarchical structures from concepts and connections
• Transaction Support (ACID Compliant) ⭐: Atomic operations with commit/rollback for data integrity
  • Atomicity: All-or-nothing operations
  • Consistency: Guaranteed valid data state
  • Isolation: Transaction isolation
  • Durability: Permanent committed changes
  • Bulk batching: Efficient multi-operation server sync

Offline & Sync

• Offline-First Architecture: Full IndexedDB support with intelligent caching and virtual ID system
• Virtual ID System: Negative IDs for local/offline, positive for synced, ghost IDs for reference preservation
• Sync Capabilities: Seamless sync between local and remote data with automatic conflict resolution
• Service Worker Support: Optional background processing for better performance

Search & Query

• FreeschemaQuery System ⭐: Flexible, schema-free querying with filters, nested relationships, and multiple output formats
• Advanced Search: Powerful search capabilities with filters, type matching, relationship queries, and recursive searches
• Binary Tree Indexing: Fast in-memory indexing for optimal performance
• Bulk Operations: Efficient batch processing for concepts, connections, and searches

Reactive & UI

• Widget System ⭐: React-like component framework with lifecycle hooks, state management, and parent-child composition
  • StatefulWidget: Full lifecycle management (before_render, render, after_render)
  • BuilderStatefulWidget: Dynamic code execution and concept integration
  • Observable Integration: Real-time UI updates when data changes
• Reactive State Management: Observable pattern with automatic change detection and subscriber notifications

Developer Experience

• Type System: Strong TypeScript typing throughout with comprehensive JSDoc documentation
• Comprehensive Documentation: All functions, classes, and methods documented with concise JSDoc comments
• Session Management: Built-in user authentication and session handling
• Transaction API: Simple, intuitive API for complex multi-step operations

Installation

npm install mftsccs-browser

Or using yarn:

yarn add mftsccs-browser

Quick Start

Basic Usage

import { init, MakeTheInstanceConceptLocal, GetTheConceptLocal } from 'mftsccs-browser';

// Initialize the package
await init({
  url: 'https://your-backend-api.com',
  clientUrl: 'https://your-app.com',
  secureCoreModePath: false
});

// Create a concept (recommended: local-first with transactions)
const newConcept = await MakeTheInstanceConceptLocal(
  'the_name',           // Type (always use "the_" prefix)
  'My First Concept',   // Value/referent
  false,                // composition mode (false = get-or-create)
  userId,               // User ID
  accessId,             // Access ID
  sessionId             // Session ID
);
console.log('Created:', newConcept);

// Retrieve a concept
const concept = await GetTheConceptLocal(newConcept.id);
console.log('Retrieved:', concept);

Using Transactions (Recommended)

The LocalTransaction class provides a robust transaction pattern with commit and rollback support. Always use transactions for multi-step operations to ensure ACID compliance and enable bulk batching to the server.

import { LocalTransaction } from 'mftsccs-browser';

// Initialize a new transaction
const transaction = new LocalTransaction();
await transaction.initialize();

try {
  // Create concepts within the transaction
  const person = await transaction.MakeTheInstanceConceptLocal(
    'the_person',     // Type
    'Alice',          // Value
    false,            // composition mode
    userId,
    accessId,
    sessionId
  );

  const email = await transaction.MakeTheInstanceConceptLocal(
    'the_email',
    '[email protected]',
    false,
    userId,
    accessId,
    sessionId
  );

  // Create connection - RECOMMENDED: Use CreateConnection ⭐
  // Auto-creates type concept, no manual MakeTheTypeConceptLocal() needed
  await transaction.CreateConnection(
    person,           // Pass concept objects directly
    email,
    'has_email'      // Type string - automatically handled
  );

  // Commit all changes to server in one atomic operation
  await transaction.commitTransaction();
  console.log('Transaction committed successfully');

} catch (error) {
  // Rollback all changes if any operation fails
  await transaction.rollbackTransaction();
  console.error('Transaction rolled back:', error);
}

Manual Transaction Tracking (Alternative Approach)

For simpler cases, you can manually track actions:

import { MakeTheInstanceConceptLocal, CreateConnection, LocalSyncData } from 'mftsccs-browser';

// Initialize actions tracker
const actions = { concepts: [], connections: [] };

// Create multiple concepts with action tracking
const person = await MakeTheInstanceConceptLocal(
  'the_person', 'Alice', false, userId, accessId, sessionId, 0, actions
);

const email = await MakeTheInstanceConceptLocal(
  'the_email', '[email protected]', false, userId, accessId, sessionId, 0, actions
);

// Create connection with action tracking - RECOMMENDED: Use CreateConnection ⭐
await CreateConnection(
  person,          // Pass concept objects
  email,
  'has_email',    // Type string - auto-creates type concept
  actions
);

// Sync all tracked changes to server in one batch
await LocalSyncData.SyncDataOnline(undefined, actions);
console.log('Synced:', actions.concepts.length, 'concepts,', actions.connections.length, 'connections');

With Service Worker (Recommended for Production)

import { init, sendMessage } from 'mftsccs-browser';

// Initialize with service worker
await init({
  url: 'https://your-backend-api.com',
  clientUrl: 'https://your-app.com',
  secureCoreModePath: true, // Enable service worker mode
  serviceWorkerPath: '/service-worker.js'
});

// All operations automatically use the service worker
const concepts = await sendMessage('getConcept', { id: 123 });

Core Concepts

1. Concept

A Concept represents an entity or node in your knowledge graph. Each concept has:

• A unique id (positive for server-synced, negative for local/virtual)
• A characterValue (text representation)
• typeId and categoryId for classification
• Relationships to other concepts via connections

Best Practice: Use MakeTheInstanceConceptLocal() to create concepts with the get-or-create pattern and transaction support. Always use the "the_" prefix for type parameters (e.g., "the_name", "the_email").

2. Connection

A Connection represents a directed relationship between two concepts:

• ofTheConceptId → toTheConceptId (from → to)
• typeId to classify the connection type
• orderId for ordering multiple connections

Best Practice: Use CreateConnection() to create connections - it's simpler and saves development time:

• ✅ Automatic Type Creation: No need to call MakeTheTypeConceptLocal() manually
• ✅ Intuitive API: Pass concept objects directly (not IDs)
• ✅ Less Boilerplate: Just provide the type string (e.g., 'has_email')
• ✅ Transaction Compatible: Works seamlessly with LocalTransaction for ACID compliance

Use CreateTheConnectionLocal() only when you need fine-grained control or already have the typeId.

3. Composition

A Composition is a structured grouping that includes:

• A main concept
• Associated connections
• Related concepts
• Nested sub-compositions

4. Transaction (ACID Compliance) ⭐

A Transaction provides atomic, consistent operations with commit and rollback capabilities:

• Atomicity: All operations succeed or fail together
• Consistency: Data remains in valid state
• Isolation: Transactions are isolated from each other
• Durability: Committed changes are permanent

Why Transactions Matter:

• ✅ Bulk Operations: Send multiple concepts/connections in a single batch to the server
• ✅ Data Integrity: Guarantee all-or-nothing operations (no partial updates)
• ✅ Rollback Support: Undo all changes if any operation fails
• ✅ Performance: Reduce network calls by batching operations
• ✅ ACID Compliant: Ensure database-level consistency guarantees

Best Practice: Use LocalTransaction class for all multi-step operations to ensure data consistency and optimal performance.

5. FreeschemaQuery (Flexible Querying) ⭐

A FreeschemaQuery is the primary querying mechanism for retrieving data from your knowledge graph:

• Schema-Free: Query without rigid schema constraints
• Declarative: Describe what you want, not how to get it
• Filters: Complex filtering with AND/OR logic operators
• Nested Queries: Navigate relationships through multiple levels
• Multiple Formats: Get data in the format that suits your use case
• Observable: Real-time updates when data changes

Key Capabilities:

• ✅ Type-Based Queries: Find all concepts of a specific type (e.g., "person", "organization")
• ✅ Complex Filters: Combine multiple filters with logical operators (=, !=, like, >, <, >=, <=)
• ✅ Relationship Navigation: Query connected concepts through typeConnections
• ✅ Deep Nesting: Build complex queries by composing multiple FreeschemaQuery objects
• ✅ Pagination: Handle large datasets efficiently with page/inpage parameters
• ✅ Reactive Updates: Use observables for automatic UI updates

Best Practice: Use FreeschemaQuery for all data retrieval operations. See the FreeschemaQuery Guide for comprehensive examples.

const transaction = new LocalTransaction();
await transaction.initialize();

try {
  // Multiple operations tracked automatically
  await transaction.MakeTheInstanceConceptLocal(...);
  await transaction.CreateConnectionBetweenTwoConceptsLocal(...);

  // Commit all changes in one atomic batch
  await transaction.commitTransaction();
} catch (error) {
  // Rollback if anything fails
  await transaction.rollbackTransaction();
}

For detailed explanations, see Core Concepts Documentation.

Documentation

Comprehensive documentation is available throughout the codebase with JSDoc comments on all functions, classes, and methods.

Documentation Guides

• Getting Started Guide: Detailed initialization and first steps
• Core Concepts: In-depth explanation of concepts, connections, and compositions
• FreeschemaQuery Guide: Complete querying system with filters, nested queries, and examples ⭐
• Widget System Guide: Component framework for building reactive UIs with lifecycle management ⭐

Inline Documentation

All code is fully documented with concise JSDoc comments:

API Layer (src/Api/)

• Create APIs: Creating concepts, connections, characters, text data, and ghost syncing
• Get/Retrieve APIs: Fetching concepts, connections, compositions (single and bulk operations)
• Search APIs: Internal search, linker-based queries, freeschema queries, recursive searches
• Delete APIs: Concept and connection deletion (single and bulk)
• Authentication APIs: Login, signin, signup functionality
• Session APIs: Session creation and visit tracking
• Utility APIs: Type concepts, prototypes, translations, images

Services Layer (src/Services/)

• Local Services (src/Services/Local/): Offline-first operations with IndexedDB
  • Concept operations (create, get, update, delete)
  • Connection management (local connections, named connections)
  • Composition handling (JSON conversion, patching, bulk retrieval)
  • Binary tree indexing for performance
  • Virtual ID system (negative IDs for local, positive for synced)
• Core Services: Main business logic for concepts, connections, and compositions

Widget System (src/Widgets/)

• BaseWidget: Foundation widget class with DOM management
• StatefulWidget: Stateful widgets with full lifecycle (mount, render, update)
• BuilderStatefulWidget: Advanced builder pattern widgets
• RenderServices: Page and widget rendering utilities
• CacheWidget: Generic caching system with LRU and TTL support
• Observable Pattern: BaseObserver for reactive UI updates

Reactive Wrappers (src/WrapperFunctions/)

• DependencyObserver: Base observable class for reactive state management
• Observable Wrappers: GetComposition, GetLink, RecursiveSearch, SchemaQuery observables
• Automatic change detection and subscriber notifications for real-time updates

API Overview

Creating Data (Recommended Approach)

import {
  MakeTheInstanceConceptLocal,
  CreateConnection,
  CreateTheCompositionLocal
} from 'mftsccs-browser';

// Create concepts (local-first, with get-or-create pattern)
const person = await MakeTheInstanceConceptLocal(
  'the_person',      // Type with "the_" prefix
  'Alice',           // Value
  false,             // composition mode: false = get-or-create, true = always create new
  userId,
  accessId,
  sessionId
);

const email = await MakeTheInstanceConceptLocal(
  'the_email',
  '[email protected]',
  false,
  userId,
  accessId,
  sessionId
);

// Create connection - RECOMMENDED: CreateConnection (simplified API) ⭐
// Automatically creates the connection type concept if it doesn't exist
const connection = await CreateConnection(
  person,               // Source concept object
  email,                // Target concept object
  'has_email'          // Type string - auto-creates type concept
);
// ✅ No need to call MakeTheTypeConceptLocal() manually!
// ✅ Pass concept objects directly (not IDs)
// ✅ Saves developer time and reduces boilerplate

// Alternative: CreateTheConnectionLocal (manual type creation required)
// Use this if you already have the typeId or need fine-grained control
const connectionTypeId = await MakeTheTypeConceptLocal('has_email', userId, userId, userId);
const manualConnection = await CreateTheConnectionLocal(
  person.id,           // Must extract ID manually
  email.id,            // Must extract ID manually
  connectionTypeId,    // Must create type concept first
  1000                 // orderId
);

// Create a composition from JSON (local-first)
const composition = await CreateTheCompositionLocal(
  {
    the_title: 'My Project',
    the_description: 'Project details...',
    the_status: 'Active'
  },
  mainConceptId,
  userId
);

Using Transactions for Batch Operations

import { MakeTheInstanceConceptLocal, LocalSyncData } from 'mftsccs-browser';

// Track all changes in a transaction
const actions = { concepts: [], connections: [] };

// Create multiple concepts with transaction tracking
const project = await MakeTheInstanceConceptLocal(
  'the_project', 'New Project', false, userId, accessId, sessionId, undefined, actions
);

const task1 = await MakeTheInstanceConceptLocal(
  'the_task', 'Task 1', false, userId, accessId, sessionId, undefined, actions
);

const task2 = await MakeTheInstanceConceptLocal(
  'the_task', 'Task 2', false, userId, accessId, sessionId, undefined, actions
);

// Sync all changes to server in one batch
await LocalSyncData.SyncDataOnline(undefined, actions);
console.log(`Synced ${actions.concepts.length} concepts and ${actions.connections.length} connections`);

Retrieving Data

import { GetTheConceptLocal, GetCompositionLocal } from 'mftsccs-browser';

// Get a concept by ID (works with both positive and negative IDs)
const concept = await GetTheConceptLocal(conceptId);

// Get a composition with all related data
const composition = await GetCompositionLocal(conceptId);

// Get composition with ID wrapper (DATAID format)
const compositionWithId = await GetCompositionLocalWithId(conceptId);

Querying Data (FreeschemaQuery) ⭐

FreeschemaQuery is the recommended way to query your knowledge graph with flexible filtering and relationship navigation.

import { FreeschemaQuery, FreeschemaQueryApi, FilterSearch, DATAID } from 'mftsccs-browser';

// Simple type-based query
const query = new FreeschemaQuery();
query.type = "person";           // Query all person concepts
query.outputFormat = DATAID;     // Structured output
query.inpage = 20;               // 20 results per page
query.page = 1;                  // First page

const results = await FreeschemaQueryApi(query, authToken);

// Query with filters
const filterQuery = new FreeschemaQuery();
filterQuery.type = "employee";

const deptFilter = new FilterSearch();
deptFilter.name = "dept_filter";
deptFilter.type = "the_department";
deptFilter.search = "Engineering";
deptFilter.logicoperator = "=";

filterQuery.filters = [deptFilter];
filterQuery.filterLogic = "( dept_filter )";

const engineers = await FreeschemaQueryApi(filterQuery, authToken);

// Query with nested relationships
const personQuery = new FreeschemaQuery();
personQuery.type = "person";
personQuery.selectors = ["the_name"];

// Get emails (nested query)
const emailQuery = new FreeschemaQuery();
emailQuery.typeConnection = "has_email";
emailQuery.name = "emails";
emailQuery.selectors = ["the_email"];

personQuery.freeschemaQueries = [emailQuery];

const personsWithEmails = await FreeschemaQueryApi(personQuery, authToken);
// Returns persons with their emails nested in the results

See the FreeschemaQuery Guide for complete documentation with advanced examples.

Legacy Search Functions

These functions are still supported but FreeschemaQuery is recommended for new code:

import { SearchConcept, SearchWithLinker, SearchWithTypeAndLinker } from 'mftsccs-browser';

// Simple search
const results = await SearchConcept('search term');

// Search with relationship filter
const linkedResults = await SearchWithLinker('search term', linkerConceptId);

// Advanced search with type and linker
const typedResults = await SearchWithTypeAndLinker('search term', typeId, linkerConceptId);

Deleting Data

import { DeleteConceptById, DeleteConnectionById } from 'mftsccs-browser';

// Delete a concept
await DeleteConceptById(conceptId);

// Delete a connection
await DeleteConnectionById(connectionId);

Configuration

Initialization Options

await init({
  // Required: Backend API URL
  url: 'https://api.example.com',

  // Required: Your application URL
  clientUrl: 'https://app.example.com',

  // Optional: Enable service worker mode (recommended for production)
  secureCoreModePath: false,

  // Optional: Custom service worker path
  serviceWorkerPath: '/sw.js',

  // Optional: Enable detailed logging
  makeBaseSecure: true,

  // Optional: Custom configuration
  identificationKey: 'your-app-key'
});

Environment Variables

For development, create a .env.development file:

BACKEND_URL=https://dev-api.example.com
CLIENT_URL=http://localhost:3000
SECURE_MODE=false

For production, create a .env.production file:

BACKEND_URL=https://api.example.com
CLIENT_URL=https://app.example.com
SECURE_MODE=true

Examples

Example 1: Building a Knowledge Graph with Transactions

import { init, LocalTransaction, GetCompositionLocal } from 'mftsccs-browser';

// Initialize
await init({ url: API_URL, clientUrl: CLIENT_URL });

// Create a transaction for atomic operations
const transaction = new LocalTransaction();
await transaction.initialize();

try {
  // Create concepts within the transaction
  const person = await transaction.MakeTheInstanceConceptLocal(
    'the_person', 'John Doe', false, userId, accessId, sessionId
  );

  const company = await transaction.MakeTheInstanceConceptLocal(
    'the_organization', 'Acme Corp', false, userId, accessId, sessionId
  );

  const role = await transaction.MakeTheInstanceConceptLocal(
    'the_role', 'Software Engineer', false, userId, accessId, sessionId
  );

  // Create connections within the transaction using simplified API ⭐
  // Auto-creates type concepts - no manual MakeTheTypeConceptLocal() needed!
  await transaction.CreateConnection(person, company, 'works_at');
  await transaction.CreateConnection(person, role, 'has_role');

  // Commit all changes atomically to server
  await transaction.commitTransaction();
  console.log('Knowledge graph created and synced successfully');

  // Get the full composition (works with synced IDs)
  const personProfile = await GetCompositionLocal(person.id);
  console.log('Person Profile:', personProfile);

} catch (error) {
  // Rollback all changes if anything fails
  await transaction.rollbackTransaction();
  console.error('Transaction failed and rolled back:', error);
}

Example 2: Searching and Filtering

import { SearchConcept, SearchWithTypeAndLinker } from 'mftsccs-browser';

// Search for all concepts matching a term
const allResults = await SearchConcept('software');

// Search for people who work at a specific company
const employees = await SearchWithTypeAndLinker(
  'engineer',
  TYPE_PERSON,
  companyConceptId
);

Example 3: Offline-First Application with Transactions

import { init, LocalTransaction, GetTheConceptLocal } from 'mftsccs-browser';

// Initialize
await init({ url: API_URL, clientUrl: CLIENT_URL });

// Create a transaction that works offline
const transaction = new LocalTransaction();
await transaction.initialize();

try {
  // Create concepts offline - gets negative virtual IDs
  const draft = await transaction.MakeTheInstanceConceptLocal(
    'the_note', 'Draft Article', false, userId, accessId, sessionId
  );
  console.log('Created offline with virtual ID:', draft.id); // Negative ID (e.g., -12345)

  // Create a composition from JSON
  const article = await transaction.CreateTheCompositionLocal(
    {
      the_title: 'My Article',
      the_content: 'Article content here...',
      the_author: 'John Doe',
      the_status: 'Draft'
    },
    draft.id,
    userId,
    accessId,
    sessionId
  );

  // Work continues offline with virtual IDs...
  console.log('Transaction has:', transaction.actions.concepts.length, 'concepts');

  // When online, commit transaction - syncs everything atomically
  await transaction.commitTransaction();
  console.log('All offline changes synced to server');

  // After sync, virtual IDs become positive (real server IDs)
  // Ghost IDs preserve original negative IDs for local references
  const synced = await GetTheConceptLocal(draft.id);
  console.log('Real ID:', synced.id, '| Ghost ID:', synced.ghostId);

} catch (error) {
  // Rollback if sync fails (stays offline)
  await transaction.rollbackTransaction();
  console.error('Transaction rolled back, data remains local:', error);
}

Example 4: Reactive State Management with Observables

import { GetCompositionListener, DependencyObserver } from 'mftsccs-browser';

// Create an observable that watches a composition
const compositionObserver = GetCompositionListener(
  conceptId,
  userId,
  'JUSTDATA', // Output format
  1,          // Page number
  10          // Items per page
);

// Subscribe to changes
compositionObserver.subscribe((data) => {
  console.log('Composition updated:', data);
  // Update your UI automatically when data changes
});

// The observer automatically detects when:
// - The concept is modified
// - Connected concepts are updated
// - Connections are added/removed
// All subscribers are notified with fresh data

Example 5: Building UI with Widget System

The Widget System provides a React-like component framework for building interactive UIs.

import { StatefulWidget, FreeschemaQuery, SchemaQueryListener, DATAID } from 'mftsccs-browser';

class PersonListWidget extends StatefulWidget {
  constructor() {
    super();
    this.state = {
      persons: [],
      loading: true
    };
  }

  // Lifecycle: Setup after mount
  before_render() {
    this.setupObserver();
  }

  setupObserver() {
    // Create query
    const query = new FreeschemaQuery();
    query.type = "person";
    query.outputFormat = DATAID;
    query.inpage = 10;
    query.selectors = ["the_name", "the_email"];

    // Nested query for phone numbers
    const phoneQuery = new FreeschemaQuery();
    phoneQuery.typeConnection = "has_phone";
    phoneQuery.name = "phone";
    phoneQuery.selectors = ["the_phone"];

    query.freeschemaQueries = [phoneQuery];

    // Subscribe to real-time updates
    SchemaQueryListener(query, "").subscribe((results) => {
      this.state.persons = results;
      this.state.loading = false;
      this.render(); // Auto-update UI
    });
  }

  // Template
  getHtml() {
    if (this.state.loading) {
      return '<div class="loading">Loading persons...</div>';
    }

    const personList = this.state.persons.map(p => `
      <div class="person-card">
        <h3>${p.person.the_name.characterValue}</h3>
        <p>Email: ${p.person.the_email?.characterValue || 'N/A'}</p>
        <p>Phone: ${p.person.phone?.the_phone?.characterValue || 'N/A'}</p>
      </div>
    `).join('');

    return `
      <div class="person-list">
        <h2>Team Members</h2>
        ${personList}
      </div>
    `;
  }
}

// Mount widget
const widget = new PersonListWidget();
widget.mount(document.getElementById('app'));

// Widget automatically updates when:
// - New persons are created
// - Existing persons are modified
// - Phone numbers change

See the Widget System Guide for complete documentation including:

• Lifecycle hooks (before_render, render, after_render)
• State management and change detection
• Parent-child widget composition
• Event handling
• BuilderStatefulWidget for dynamic code execution
• Complete examples (Todo list, Dashboard, Forms)

Development

Setup for Development

1. Clone the repository:

git clone https://github.com/Mentor-Friends/tsccs-dev.git
cd tsccs-dev

2. Install dependencies:

npm install

3. Create environment file:

cp .env.example .env.development

4. Edit .env.development with your configuration

Build Commands

# Development build with watch mode
npm run dev

# Production build
npm run build

# Start production bundle
npm start

Project Structure

src/
├── Api/                    # API endpoint wrappers (55+ documented functions)
│   ├── Create/            # Create operations (concepts, connections, ghost sync)
│   ├── Delete/            # Delete operations
│   ├── Search/            # Search APIs (internal, linker, freeschema)
│   ├── Session/           # Session management
│   ├── SearchConcept/     # Concept search utilities
│   └── ...                # Get, Retrieve, and utility APIs
├── Services/              # Business logic and operations
│   ├── Local/             # Local/offline operations (21 documented files)
│   └── ...                # Core services
├── Widgets/               # UI widget system (13 documented files)
│   ├── BaseWidget.ts      # Foundation widget class
│   ├── StatefulWidget.ts  # Stateful widget with lifecycle
│   └── ...                # Render services, caching, observers
├── WrapperFunctions/      # Reactive observable wrappers (8 documented files)
├── DataStructures/        # Core data models (Concept, Connection, etc.)
├── Database/              # IndexedDB management
├── Constants/             # Configuration constants
├── Middleware/            # Logging, monitoring, error handling
├── ServiceWorker/         # Service worker implementation
└── app.ts                 # Main entry point and exports

Documentation Coverage

All code is fully documented with concise JSDoc comments:

• ✅ 55+ API functions documented (Create, Get, Search, Delete, Session, etc.)
• ✅ 21 Local Service files documented (offline-first operations)
• ✅ 13 Widget files documented (UI framework with 76+ methods)
• ✅ 8 Observable wrappers documented (reactive state management)
• ✅ All parameters, return types, and complex logic explained
• ✅ Examples provided for key functions
• ✅ Professional, concise style for quick understanding

Publishing to npm

Prerequisites

1. Ensure you have an npm account: Sign up at npmjs.com
2. Login to npm from your terminal:

npm login

Pre-publish Checklist

Before publishing, ensure:

• [ ] Version number is updated in package.json
• [ ] All tests pass: npm test
• [ ] Build succeeds: npm run build
• [ ] README.md is up to date
• [ ] CHANGELOG.md documents changes (if applicable)
• [ ] Git repository is clean and committed

Publishing Steps

1. Update Version

Use semantic versioning (MAJOR.MINOR.PATCH):

# For bug fixes
npm version patch

# For new features (backwards compatible)
npm version minor

# For breaking changes
npm version major

This automatically:

• Updates version in package.json
• Creates a git commit
• Creates a git tag

2. Build the Package

npm run build

This creates the dist/ folder with:

• dist/main.bundle.js - Main bundle
• dist/types/ - TypeScript declarations

3. Test the Package Locally (Optional but Recommended)

# Create a tarball
npm pack

# This creates mftsccs-browser-X.X.X.tgz
# Test it in another project:
cd /path/to/test-project
npm install /path/to/mftsccs-browser-X.X.X.tgz

4. Publish to npm

# For beta/pre-release versions
npm publish --tag beta

# For stable releases
npm publish

5. Push to Git

git push origin main --tags

Publishing Beta Versions

For testing before stable release:

# Update to beta version
npm version 2.1.171-beta

# Build
npm run build

# Publish with beta tag
npm publish --tag beta

# Users can install with:
# npm install mftsccs-browser@beta

Automated Publishing with GitHub Actions (Recommended)

Create .github/workflows/publish.yml:

name: Publish to npm

on:
  release:
    types: [created]

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: '18'
          registry-url: 'https://registry.npmjs.org'
      - run: npm install
      - run: npm run build
      - run: npm test
      - run: npm publish
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Then:

1. Add your npm token to GitHub Secrets as NPM_TOKEN
2. Create a GitHub release
3. The package publishes automatically

Managing Versions

# View current version
npm version

# View published versions
npm view mftsccs-browser versions

# Unpublish a version (within 72 hours)
npm unpublish [email protected]

# Deprecate a version
npm deprecate [email protected] "Use version 2.1.171 instead"

Package Scope and Access

This package is currently unscoped. To publish as a scoped package:

1. Update package.json:

{
  "name": "@mentor-friends/mftsccs-browser"
}

2. Publish with public access:

npm publish --access public

Contributing

Contributions are welcome! Please follow these steps:

1. Fork the repository
2. Create a feature branch: git checkout -b feature/my-feature
3. Make your changes
4. Add tests for new functionality
5. Commit your changes: git commit -am 'Add new feature'
6. Push to the branch: git push origin feature/my-feature
7. Submit a pull request

Coding Standards

• Follow TypeScript best practices
• Maintain existing code style
• Add concise JSDoc comments for all public APIs and functions
  • Keep descriptions brief (1-3 sentences)
  • Document all parameters with types
  • Include return value documentation
  • Add examples for complex functions
  • Mark complex logic with "Complex Logic" callouts
• Write unit tests for new features
• Update documentation as needed

Support

• Issues: GitHub Issues
• Repository: https://github.com/Mentor-Friends/tsccs-dev

License

ISC License - see LICENSE file for details.

Author

Mentor Friends

Made with ❤️ by the Mentor Friends team