mnemonica 0.9.99777 → 0.9.99779

package/README.md

@@ -1,5 +1,6 @@
-# mnemonica is
-abstract technique that aids information retention : instance inheritance system
+# mnemonica
+
+**Abstract technique that aids information retention: Instance Inheritance System**
 
 ... allows us to make inherited descriptions of mappings of transformations from predecessor structured data types to the successors, as if it was math `f(x)=>y` ... and we will use `this` keyword as a persistent data structure where we will apply that transformations
 
@@ -10,823 +11,981 @@ abstract technique that aids information retention : instance inheritance system
 
 # shortcuts
 
+* ?. : state : **mad science**
 * ?. : type : **asynchronous monad descriptor** => this
 * ?. : prod ready : **we wonder about**
 * ?. : example : **git clone && npm run example**
 
 ---
-
 [![Coverage Status](https://coveralls.io/repos/github/wentout/mnemonica/badge.svg?branch=master)](https://coveralls.io/github/wentout/mnemonica?branch=master)
-
 ![NPM](https://img.shields.io/npm/l/mnemonica)
 ![GitHub package.json version](https://img.shields.io/github/package-json/v/wentout/mnemonica)
 ![GitHub last commit](https://img.shields.io/github/last-commit/wentout/mnemonica)
-
 [![NPM](https://nodei.co/npm/mnemonica.png?mini=true)](https://www.npmjs.com/package/mnemonica)
 
 ---
 
+## Table of Contents
+
+- [Overview](#overview)
+- [Installation](#installation)
+- [Quick Start](#quick-start)
+- [Core Concepts](#core-concepts)
+- [TypeScript Support](#typescript-support)
+- [API Reference](#api-reference)
+  - [Core Functions](#core-functions)
+  - [Type Reference](#type-reference)
+  - [Type Management](#type-management)
+  - [Instance Methods](#instance-methods)
+  - [Utilities](#utilities)
+  - [Hooks](#hooks)
+  - [Error Handling](#error-handling)
+  - [Symbols & Constants](#symbols--constants)
+- [Configuration Options](#configuration-options)
+- [AI Agent Usage Guide](#ai-agent-usage-guide)
+- [Examples](#examples)
+
+---
+
+## Overview
 
-# core concept
+Mnemonica helps create ordered sequences of data transformations using prototype chain inheritance. It combines Object Instances with Inheritance through the Prototype Chain, enabling you to create new instances inherited from existing ones.
 
-This lib might help to create some sort of order or sequence or precedence of how we modify data inside of our code. It utilizes the concept of tree or [Trie](https://en.wikipedia.org/wiki/Trie) by combining both: Object Instances and Inheritance through the Prototype Chain, where we are able to create new instance inherited from existing one as much times as we need. It might look like obvious, but ... we tell about Instances, not about Classes, meaning Plain Objects, crafted from real Constructors before we start the process of inheriting them one from another. In an attempt to describe this approach let me suggest this articles:
+Think of it as a mathematical function `f(x) => y` where `this` is your persistent data structure and transformations are applied sequentially.
 
-* [Inheritance in JavaScript : Factory of Constructors with Prototype Chain](https://github.com/mythographica/stash/blob/master/inheritance.md)
-* [Architecture of Prototype Inheritance in JavaScript](https://dev.to/wentout/architecture-of-prototype-inheritance-in-javascript-ce6)
-* [Dead Simple type checker for JavaScript](https://dev.to/wentout/dead-simple-type-checker-for-javascript-4l40)
+> *"O Great Mnemosyne! Please! Save us from Oblivion..."*
+> — from the source, where memory persists
 
+![concept](https://raw.githubusercontent.com/mythographica/stash/master/img/LifeCycle/LifeCycle.png)
+
+**Key Features:**
+- Factory of Constructors with Prototype Chain Inheritance
+- Instance-level inheritance (not just class-level)
+- Async constructor support with chainable awaits
+- Type-safe data flow definition
+- Comprehensive hook system for lifecycle events
 
-## TypeScript note
+**Related Reading:**
+- [Inheritance in JavaScript: Factory of Constructors with Prototype Chain](https://github.com/mythographica/stash/blob/master/inheritance.md)
+- [Architecture of Prototype Inheritance in JavaScript](https://dev.to/wentout/architecture-of-prototype-inheritance-in-javascript-ce6)
+- [Dead Simple type checker for JavaScript](https://dev.to/wentout/dead-simple-type-checker-for-javascript-4l40)
 
-**define** function now fully supports TypeScript definitions
+---
 
-for more easy types writing nested~sub constructors might be applied using just direct apply, call or bind functions
+## Installation
 
+```bash
+npm install mnemonica
+```
+
+**Requirements:** Node.js >=16 <24
+
+---
 
-## Factory of Constructors
+## Quick Start
 
-As we discrovered from that article, we need some tooling, giving us the best experience with Prototype Chain Inheritance pattern. First of all it must be reproducible and maintainable. And from the first point we have to define some sort of Factory Constructor for start crafting our Instances, it might look like so:
+### CommonJS
 
 ```js
 const { define } = require('mnemonica');
 
-const TypeModificationProcedure = function (opts) {
-	Object.assign(this, opts);
-};
+// Define a type
+const UserType = define('UserType', function (data) {
+  Object.assign(this, data);
+});
 
-// SomeTypeConstructor -- is a constructor.name
-const SomeType = define('SomeTypeConstructor',
-	TypeModificationProcedure,
-);
+// Create an instance
+const user = new UserType({ name: 'John', email: 'john@example.com' });
+
+// Define a subtype
+const AdminType = UserType.define('AdminType', function () {
+  this.role = 'admin';
+});
 
+// Create nested instance (inherits from user)
+const admin = new user.AdminType();
+console.log(admin.name); // 'John' (inherited)
+console.log(admin.role); // 'admin' (own property)
 ```
 
-Or, we can define `SomeType` like this:
+### ESM
 
 ```js
-const TypeModificationConstructorFactory = () => {
-	// SomeTypeConstructor -- is a constructor.name
-	const SomeTypeConstructor = function (opts) {
-		// as this is absolutely the same behaviour
-		// we described upper
-		// in TypeModificationProcedure
-		// we allowed to do the following
-		// for shortening this example lines
-		Object.assign(this, opts);
-	};
-	// prototype definition is NOT obligatory
-	SomeTypeConstructor.prototype
-		.description = 'SomeType Constructor';
+import { define, lookup } from 'mnemonica/module';
+```
 
-	return SomeTypeConstructor;
-};
+---
 
-const SomeType = define(TypeModificationConstructorFactory);
-```
-
-Or using Classes:
-
-```js
-const TypeModificationConstructorFactory = () => {
-	// SomeTypeConstructor -- is a constructor.name
-	class SomeTypeConstructor {
-		constructor (opts) {
-			// all this definitions
-			// just to show the example
-			// of how it works
-			const {
-				some,
-				data,
-				// we will re-define
-				// "inside" property later
-				// using nested sub-type
-				inside
-			} = opts;
-			this.some = some;
-			this.data = data;
-			this.inside = inside;
-		}
-	};
-	return SomeTypeConstructor;
-};
+## Core Concepts
+
+### Factory of Constructors
+
+Define types using constructors, factory functions, or classes:
+
+```js
+// Using a constructor function
+const SomeType = define('SomeType', function (opts) {
+  Object.assign(this, opts);
+});
 
-const SomeType = define(TypeModificationConstructorFactory);
+// Using a factory function
+const AnotherType = define(() => {
+  const AnotherTypeConstructor = function (opts) {
+    Object.assign(this, opts);
+  };
+  AnotherTypeConstructor.prototype.description = 'SomeType Constructor';
+  return AnotherTypeConstructor;
+});
+
+// Using a class
+const ClassType = define(() => {
+  class MyClass {
+    constructor(opts) {
+      Object.assign(this, opts);
+    }
+  }
+  return MyClass;
+});
 ```
 
-Then we can define some nested type, using our crafted `SomeType` definition:
+### Nested Type Definition
 
 ```js
-SomeType.define('SomeSubType', function (opts) {
-	const {
-		other,
-		inside // again
-	} = opts;
-	this.other = other;
-	// here we will re-define
-	// our previously defined property
-	// with the new value
-	this.inside = inside;
+// Define nested types
+SomeType.define('SubType', function (opts) {
+  this.other = opts.other;
 }, {
-	description : 'SomeSubType Constructor'
+  description: 'SomeSubType Constructor'
 });
 
-// or, absolutely equal
-SomeType.SomeSubType = function (opts) {
-	const {
-		other,
-		inside // again
-	} = opts;
-	this.other = other;
-	// here we will re-define
-	// our previously defined property
-	// with the new value
-	this.inside = inside;
+// Or using assignment
+SomeType.SubType = function (opts) {
+  this.other = opts.other;
 };
-SomeType.SomeSubType.prototype = {
-	description : 'SomeSubType Constructor'
+SomeType.SubType.prototype = {
+  description: 'SomeSubType Constructor'
 };
 ```
 
-Now our type modification chain looks like this:
+### Instance Creation and Inheritance
 
 ```js
-// 1.
-SomeType
-	// 1.1
-	.SomeSubType;
-```
+const someInstance = new SomeType({
+  some: 'arguments',
+  data: 'necessary'
+});
+
+const subInstance = new someInstance.SubType({
+  other: 'data needed'
+});
 
-And we can continue nesting sub-types as far as it might be necessary for our code and our software architecture... :^)
+// All properties are inherited
+console.log(subInstance.some);   // 'arguments' (inherited)
+console.log(subInstance.other);  // 'data needed' (own)
+```
 
-## **How it Works then**
+### The `.extract()` Method
 
-Let's create an instance, using `SomeType` construtor, we earlier.
+Extract all inherited properties into a flat object:
 
 ```js
-const someTypeInstance = new SomeType({
-	some   : 'arguments',
-	data   : 'necessary',
-	inside : 'of SomeType definition'
-});
+const extracted = subInstance.extract();
+// Result: { data, description, other, some }
+
+// Or use the standalone utility
+const { utils: { extract } } = require('mnemonica');
+const extracted2 = extract(subInstance);
 ```
 
-Then, there might be situation, when we reached the place in code, where we have to use the next, nested -- `SomeSubType` -- constructor, to apply our `someTypeInstance` to the next one Inherited and **`Sub-Type'd`** Instance.
+---
 
-```js
+## TypeScript Support
 
-const someSubTypeInstance =
-	// someTypeInstance is an instance
-	// we did before, through the referenced
-	// SomeType constructor we made using
-	// define at the first step
-	// of this fabulous adventure
-	someTypeInstance
-		// we defined SomeSubType
-		// as a nested constructor
-		// so we have to use it
-		// utilising  instance
-		// crafted from it's parent
-		.SomeSubType({
-			other  : 'data needed',
-			// and this is -re-definition
-			// of "inside" property
-			// as we promised before
-			inside : ' of ... etc ...'
-		});
+The `define` function has full TypeScript support with comprehensive type definitions:
 
-```
+```typescript
+import { define, apply, call, bind } from 'mnemonica';
 
-At this moment all stored data will inherit from `someTypeInstance` to `someSubTypeInstance`. Moreover, `someSubTypeInstance` become instanceof `SomeType` and `SomeSubType` and, let's go deeper, instance of `someTypeInstance`.
+interface UserData {
+  email: string;
+  password: string;
+}
 
+const UserType = define('UserType', function (this: UserData, data: UserData) {
+  Object.assign(this, data);
+});
 
-And now let's ponder on our Instances:
+// Nested constructors work with apply/call/bind for type inference
+const user = new UserType({ email: 'test@test.com', password: 'secret' });
+```
 
-```js
+For complex nested types, use `apply`, `call`, or `bind` for better type inference:
 
-console.log(someTypeInstance);
+```typescript
+const SomeSubType = SomeType.define('SomeSubType', function (...args: string[]) {
+  // ...
+});
 
-	some   : 'arguments'
-	data   : 'necessary'
-	inside : 'of SomeType definition'
+const someInstance = new SomeType();
+const subInstance = call(someInstance, SomeSubType, 'arg1', 'arg2');
+```
 
-console.log(someSubTypeInstance);
+### Exported Type Definitions
 
-	other  : 'data needed'
-	inside : ' of ... etc ...'
+The following types are available for advanced TypeScript usage:
 
+```typescript
+import {
+  // Core constructor types
+  IDEF,                          // Base constructor function type: { new(): T } | { (this: T, ...args): void }
+  ConstructorFunction,           // Constructor with prototype
+  Constructor,                   // Generic constructor type
+  
+  // Instance types
+  MnemonicaInstance,             // Instance methods interface (extract, pick, parent, fork, etc.)
+  Props,                         // Internal instance properties (__type__, __args__, __parent__, etc.)
+  SiblingAccessor,               // Sibling type accessor type
+  
+  // Type definition types
+  TypeClass,                     // Base type constructor returned by define()
+  IDefinitorInstance,            // Definitor instance with define/lookup methods and subtypes
+  DecoratedClass,                // Type for @decorate decorated classes
+  TypeDef,                       // Type definition object structure
+  
+  // Configuration types
+  constructorOptions,            // Type config options (strictChain, blockErrors, etc.)
+  hooksTypes,                    // 'preCreation' | 'postCreation' | 'creationError'
+  hook,                          // Hook callback type
+  hooksOpts,                     // Hook options passed to callbacks
+  CollectionDef,                 // Types collection definition
+  
+  // Utility function types
+  ApplyFunction,                 // apply(entity, Ctor, args) => S
+  CallFunction,                  // call(entity, Ctor, ...args) => S
+  BindFunction,                  // bind(entity, Ctor) => (...args) => S
+} from 'mnemonica';
 ```
 
-So, here it might be looking miscouraging... but this is not the end of the story, cause we have the magic of **built-in** ...
+### Generic Type Patterns
 
-# .extract()
+Define types with proper generic constraints for full type safety:
 
-So, here is a situation we need all previously defined props and all the nested props collected to the one-same object:
+```typescript
+// Using IDEF with interface definitions
+interface UserData {
+  email: string;
+  password: string;
+}
 
-```js
+// Type-safe constructor with 'this' context
+const UserType = define('UserType', function (this: UserData, data: UserData) {
+  Object.assign(this, data);
+});
+
+// Type-safe nested types with merged interfaces
+interface AdminData {
+  role: string;
+}
 
-const extracted = someSubTypeInstance.extract();
+const AdminType = UserType.define('AdminType', function (this: UserData & AdminData, role: string) {
+  this.role = role;
+  this.email; // string - inherited from UserData
+});
+```
 
-console.log(extracted);
+### Async Constructor Type Patterns
 
-	data        : "necessary"
-	description : "SomeSubType Constructor"
-	inside      : " of ... etc ..."
-	other       : "data needed"
-	some        : "arguments"
+```typescript
+// Async type with proper return type
+const AsyncType = define('AsyncType', async function (this: UserData, data: string) {
+  await someAsyncOperation();
+  return Object.assign(this, { data });
+});
 
+// With explicit awaitReturn option (no return required)
+const AsyncTypeNoReturn = define('AsyncType', async function () {
+  // No return needed
+}, { awaitReturn: false });
 ```
 
-or, with the same behaviour:
+---
 
-```js
-const { extract } = require('mnemonica').utils;
-const extracted = extract(someSubTypeInstance);
+## API Reference
 
-	data        : "necessary"
-	description : "SomeSubType Constructor"
-	inside      : " of ... etc ..."
-	other       : "data needed"
-	some        : "arguments"
+### Core Functions
 
-console.log(extract(someTypeInstance));
+#### `define(typeName, constructHandler, config?)`
 
-	data        : "necessary"
-	description : "SomeType Constructor"
-	inside      : "of SomeType definition"
-	some        : "arguments"
+Defines a new type constructor. Returns a TypeClass.
 
+```js
+const MyType = define('MyType', function (data) {
+  Object.assign(this, data);
+}, {
+  strictChain: true,
+  blockErrors: true
+});
 ```
 
-Here `extracted` object will contain all iterable props of `someSubTypeInstance`. It means props are accessible via `Symbol.iterator`. So if you will define some hidden props, it will not consume them. This technique allows us acheive concentration only on meaningfull parts of [Data Flow Definition](https://en.wikipedia.org/wiki/Data-flow_diagram). So, all this might help to cover the gap between declared data flow and indeed flow written in code through describing flow itself with that simple way. For sure you are free to make your own `.extractor()` functions on the top of acheived multiplie inherited data object (storage):
+**Parameters:**
+- `typeName` (string): Name of the type (optional if using factory function)
+- `constructHandler` (Function): Constructor function
+- `config` (object, optional): Configuration options
 
-![Inheritance of someSubTypeInstance](https://raw.githubusercontent.com/mythographica/stash/master/img/doc.example.png)
+#### `lookup(typeNestedPath)`
 
-And back to definitions, for sure, all of the following is true:
+Looks up a type by its nested path.
 
 ```js
-
-console.log(someTypeInstance instanceof SomeType); // true
-console.log(someSubTypeInstance instanceof SomeType); // true
-console.log(someSubTypeInstance instanceof SomeSubType); // true
-// who there can care... but, yes, it is again: true
-console.log(someSubTypeInstance instanceof someTypeInstance);
-
+const { lookup } = require('mnemonica');
+const SomeType = lookup('SomeType');
+const SomeNestedType = lookup('SomeType.SomeNestedType');
 ```
 
-But this is not the end... it might be discouraging, but this is only the begining.
-
-## How do we use defined "mnemonicas"
+#### `apply(entity, Constructor, args?)`
 
-Suppose we have to handle the `request.data` somewhere in our code and we have to consume it someelsewhere. Let's imagine us inside of **[ETL process](https://en.wikipedia.org/wiki/Extract,_transform,_load)**.
-
-Let's create Constructor for this sort of data.
+Applies a constructor to an entity with an array of arguments.
 
 ```js
-const RequestDataTypeModificator = 
-	define('RequestData',
-		FactoryOfRequestHandlerCostructor);
+const { apply } = require('mnemonica');
+const subInstance = apply(parentInstance, SubType, ['arg1', 'arg2']);
 ```
 
-Then we will use it in our code like this:
+#### `call(entity, Constructor, ...args)`
+
+Calls a constructor on an entity with spread arguments.
 
 ```js
-(req, res) => {
-	const requestInstance = 
-		RequestDataTypeModificator(req.body);
-};
+const { call } = require('mnemonica');
+const subInstance = call(parentInstance, SubType, 'arg1', 'arg2');
 ```
 
-And then it might be necessary to jump to the next part of code, which cooperate with some Storage or Daba Base.
+#### `bind(entity, Constructor)`
+
+Binds a constructor to an entity, returning a function.
 
 ```js
-const GoneToTheDataBase = 
-	RequestDataTypeModificator.
-		// jumped data definition
-		define('GoneToTheDataBase',
-			DataBaseRequestHandlerCostructor);
+const { bind } = require('mnemonica');
+const createSub = bind(parentInstance, SubType);
+const subInstance = createSub('arg1', 'arg2');
 ```
 
-Here we might choose what to do: inspect some collected data or probably we wish to extract it for **tests** or **log** or even grab them with the other consumer. And yes, we already saw `.extract()` method, but there are also two other methods could be much more helpfull...
+#### `decorate(target?, config?)`
 
-# Pre & Post creation Hooks
+TypeScript decorator for class-based definitions.
 
-```js
-// callback will be called Before requestInstance creation
+```typescript
+import { decorate } from 'mnemonica';
 
-const preCreationCallback = (hookData) => {
-	const {
-		
-		// { string }
-		TypeName : TypeModificatorConstructor.name,
-		
-		// 1. [ array ]
-		// ...args of TypeModificator
-		// for instance creation
-		argumentsOfTypeModificator,
-		
-		// 2. { object }
-		// instance we will craft from
-		// using our TypeModificator
-		instanceUsedForInheritance
-		
-	} = hookData;
-	// some necessary pre-investigations
-};
+@decorate()
+class MyClass {
+  field: number = 123;
+}
 
-RequestDataTypeModificator
-	.registerHook(
-		'preCreation', 
-			preCreationCallback);
-
-
-const postCreationCallback = (hookData) => {
-	const {
-		// { string }
-		TypeName : TypeModificatorConstructor.name,
-		
-		// 1. [ array ]
-		argumentsOfTypeModificator,
-		
-		// 2. { object }
-		instanceUsedForInheritance,
-		
-		// 3. { object }
-		// instance we just crafted
-		// from instanceUsedForInheritance
-		// using our TypeModificator
-		// with argumentsOfTypeModificator
-		// and ... inheritedInstance
-		//  .constructor.name is 
-		// TypeName
-		inheritedInstance
-		
-	} = hookData;
-	// some necessary post-investigations
-};
+// With configuration
+@decorate({ strictChain: false })
+class ConfiguredClass {
+  // ...
+}
 
-// callback will be called After requestInstance creation
-RequestDataTypeModificator
-	.registerHook(
-		'postCreation', 
-			postCreationCallback);
+// Nested decoration
+@decorate()
+class ParentClass {}
+
+@decorate(ParentClass)
+class ChildClass {}
 ```
 
-Thouse hooks will be proceeded if you register them... for each instance you will craft using `RequestDataTypeModificator`. So if you wish to investigate instances of `GoneToTheDataBase` type modificator then you have to register the other hooks for it:
+#### `registerHook(Constructor, hookType, callback)`
 
-```js
+Registers a hook for a specific constructor.
 
-GoneToTheDataBase
-	.registerHook(
-		'preCreation', // ...
-		
-GoneToTheDataBase
-	.registerHook(
-		'postCreation', // ...
-	
+```js
+const { registerHook } = require('mnemonica');
 
+registerHook(MyType, 'preCreation', (hookData) => {
+  console.log('Creating:', hookData.TypeName);
+});
 ```
 
+---
+
+### Type Reference
+
+For advanced TypeScript usage, the following types are exported from `mnemonica`:
+
+| Type | Description | Usage |
+|------|-------------|-------|
+| `IDEF<T>` | Base constructor function type | `define('Name', fn: IDEF<MyType>)` |
+| `MnemonicaInstance` | Instance methods interface | `instance.extract()`, `instance.pick()` |
+| `TypeClass` | Base type constructor | `const MyType: TypeClass = define(...)` |
+| `DecoratedClass<T>` | Decorated class type | `@decorate() class MyClass {}` |
+| `IDefinitorInstance<N, S>` | Constructor with subtypes | Returned by `define()` with `.define()` method |
+| `ConstructorFunction<T>` | Constructor with prototype | Generic constructor function signature |
+| `constructorOptions` | Configuration options | `{ strictChain: true, blockErrors: true }` |
+| `hooksTypes` | Hook type literals | `'preCreation' \| 'postCreation' \| 'creationError'` |
+| `hook` | Hook callback type | `(opts: hooksOpts) => void` |
+| `hooksOpts` | Hook options object | Passed to hook callbacks |
+| `TypeDef` | Type definition structure | `instance.__type__` structure |
+| `CollectionDef` | Types collection | `instance.__collection__` structure |
+| `ApplyFunction` | apply() function type | `apply<E, T, S>(entity, Ctor, args) => S` |
+| `CallFunction` | call() function type | `call<E, T, S>(entity, Ctor, ...args) => S` |
+| `BindFunction` | bind() function type | `bind<E, T, S>(entity, Ctor) => (...args) => S` |
+
+These types enable complete type safety when defining and using mnemonica types in TypeScript projects.
+
+---
+
+### Type Management
 
-And even more. You can use Hooks with Types Collections also (starting from v0.3.1). For doing this just grab referer to collection somewhere, for example:
+#### `defaultTypes`
 
+The default types collection. All types defined with the top-level `define()` are stored here.
 
 ```js
-const {
-	defaultTypes
-} = require('mnemonica');
+const { defaultTypes } = require('mnemonica');
+const MyType = defaultTypes.MyType;
+```
 
-defaultTypes
-	.registerHook(
-		'preCreation', preCreationTypesCollectionCallback);
-		
-defaultTypes
-	.registerHook(
-		'postCreation', postCreationTypesCollectionCallback);
+#### `createTypesCollection(config?)`
 
+Creates a new isolated types collection.
 
+```js
+const { createTypesCollection } = require('mnemonica');
+const myCollection = createTypesCollection();
+const MyType = myCollection.define('MyType', function () {});
 ```
 
-'Pre' hooks for Types Collections invoked before Type Hook invocation. 'Post' hooks for Types Collections invoked after Type Hook invocation. So, actually it looks like:
+#### `getProps(instance)` / `setProps(instance, values)`
+
+Get or set internal properties of an instance.
 
 ```js
+const { getProps, setProps } = require('mnemonica');
 
-// 1.
-typecollection.invokeHook('preCreation', // ...
+const props = getProps(instance);
+console.log(props.__type__, props.__args__);
 
-// 2.
-type.invokeHook('preCreation', // ...
+// Set properties
+setProps(instance, { __timestamp__: Date.now() });
+```
 
-// 3. instance creation is here
+---
 
-// 4.
-type.invokeHook('postCreation', // ...
+### Instance Methods
 
-// 5.
-typecollection.invokeHook('postCreation', // ...
+All mnemonica instances have the following methods:
 
+#### `.extract()`
 
+Extracts all inherited properties into a single flat object.
+
+```js
+const extracted = instance.extract();
 ```
 
-As we can see, type hooks are closest one to the type itself. For sure, there can be situations, when you have to register some common hooks, but not for `typecollection`. Assume you have some friendly types, might be from different collections, and you have to register the same hooks definitions for them. And the plase where you wish to do this is the file, other than files you defined that types. There you can use:
+#### `.pick(...keys)` / `.pick([keys])`
 
-# .lookup('TypeName')
+Picks specific properties from the instance and its inheritance chain.
 
 ```js
-const {
-	lookup
-} = require('mnemonica');
+const picked = instance.pick('email', 'password');
+// or
+const picked = instance.pick(['email', 'password']);
+```
 
-const SomeType = lookup('SomeType');
-const SomeNestedType = lookup('SomeType.SomeNestedType');
+#### `.parent(constructorName?)`
+
+Gets the parent instance. If `constructorName` is provided, walks up the chain.
 
+```js
+const immediateParent = instance.parent();
+const specificParent = instance.parent('UserType');
 ```
 
-And now it is not so necessary easy to explain why it could be usefull to use nested definitions. Sure you can do them by using the following technique: 
+#### `.clone`
+
+Property that returns a cloned instance (same parent, same args).
 
 ```js
+const cloned = instance.clone;
+// Note: For async constructors, use: await instance.clone
+```
 
-define('SomeExistentType.SomeExistentNestedType.NewType', function () {
-	// operators
-});
+#### `.fork(...args)`
 
-// or from tm descriptor
-// if you have reference
-SomeExistentType.define('SomeExistentNestedType.NewType', function () {
-	// operators
-});
+Creates a forked instance from the same parent with optional new arguments.
 
-// you can also use
+```js
+const forked = instance.fork();           // same args
+const forkedWithNewArgs = instance.fork('new', 'args');
+// Note: For async constructors, use: await instance.fork(...)
+```
 
-SomeExistentType.define('SomeExistentNestedType', () => {
-	// name of "NewType" is here
-	// nested inside of delcaration
-	return class NewType {
-		constructor (str) {
-			// operators
-		}
-	};
-});
+#### `.fork.call(thisArg, ...args)` / `.fork.apply(thisArg, args)`
 
+Forks with a different `this` context (useful for Directed Acyclic Graphs).
+
+```js
+const dagInstance = instanceA.fork.call(instanceB, 'args');
 ```
 
-# .parent('TypeName')
+#### `.exception(error, ...args)`
 
-Let assume our `instance` has indeed deep prototype chain:
+Creates an exception instance from the current instance.
 
 ```js
-EvenMore
-	.MoreOver
-		.OverMore
-			// ...
-			// ...
-			.InitialType
+const error = someInstance.exception(new Error('Something went wrong'));
+throw error;
 ```
 
-And we wish to get reference to one of the prececessors, though we have only reference to insance itself. Here we can use builtin `instance.parent()` method:
+#### `.sibling(typeName)` / `.sibling.TypeName`
+
+Access sibling types from the same collection.
 
 ```js
+const siblingType = instance.sibling('OtherType');
+const sibling = instance.sibling.OtherType;
+```
 
-// fisrst parent
-// simply equal to getProps(instance).__parent__
-const parent = instance.parent();
+---
 
-// deep parent from chain
-const parent = instance
-	.parent( 'DeepParentName' );
+### Instance Properties (via `getProps`)
 
-```
+All instances have non-enumerable internal properties:
 
+| Property | Type | Description |
+|----------|------|-------------|
+| `.__args__` | `unknown[]` | Arguments used for instance creation |
+| `.__type__` | `TypeDef` | Type definition object |
+| `.__parent__` | `object` | Parent instance reference |
+| `.__subtypes__` | `Map<string, object>` | Map of available subtypes |
+| `.__collection__` | `CollectionDef` | Types collection where type was defined |
+| `.__stack__` | `string` | Stack trace (if `submitStack: true` in config) |
+| `.__creator__` | `TypeDef` | Instance creator reference |
+| `.__timestamp__` | `number` | Creation timestamp (ms since epoch) |
+| `.__self__` | `object` | Self reference to the instance |
 
-# SomeType.call ( this_obj, ...args)
-You can combine existing TypeConstructor with any instance, even with Singletones:
+---
 
-```js
-const usingProcessAsProto = Singletoned.call(process, {
-	some   : 'arguments',
-	data   : 'necessary',
-	inside : 'for definition'
-});
-console.log(typeof instanceUsingProcessSingletone.on) // function
-```
+### Utilities
 
-or you can combine with window, or document or...
+Access via `utils` export:
 
 ```js
+const { utils } = require('mnemonica');
+```
 
-const usingWindowAsProto = Windowed.call(window);
-const usingDocumentAsProto = Documented.call(document);
-const usingJQueryAsProto = JQueried.call(jQuery);
+#### `utils.extract(instance)`
+Standalone extract function.
 
-// or even ReactDOM
-import ReactDOM from "react-dom";
-import { define } from "mnemonica";
-const ReactDOOMed = define("ReactDOOMed", function() {});
-const usingReactAsProto = ReactDOOMed.call(ReactDOM);
+#### `utils.pick(instance, ...keys)`
+Standalone pick function.
 
-const root = document.getElementById("root");
-usingReactAsProto.render("just works", root);
+#### `utils.parent(instance, constructorName?)`
+Standalone parent function.
 
+#### `utils.parse(instance)`
+Parses an instance structure, returning:
+- `name`: constructor name
+- `props`: extracted properties
+- `self`: the instance itself
+- `proto`: prototype object
+- `joint`: prototype properties
+- `parent`: parent prototype
+
+```js
+const { utils: { parse } } = require('mnemonica');
+const parsed = parse(instance);
 ```
 
+#### `utils.merge(A, B, ...args)`
+Merges two instances using fork semantics.
 
-# call, apply & bind ( existent, ItsNestedType, ...args)
+```js
+const merged = utils.merge(instanceA, instanceB, 'args');
+// Note: For async constructors, use: await utils.merge(...)
+```
 
-mostly for TypeScript purpose you may do this
+#### `utils.toJSON(instance)`
+Serializes an instance to JSON.
 
 ```js
-const SomeType = define('SomeType', function () {
-	// ...
-});
+const json = utils.toJSON(instance);
+```
 
+#### `utils.collectConstructors(instance, flat?)`
+Collects all constructors in the instance's prototype chain.
 
-const SomeSubType = SomeType
-	.define('SomeSubType', function (...args) {
-		// ...
-	});
+```js
+const constructors = utils.collectConstructors(instance, true);
+```
 
-const someInstance = new SomeType;
+---
 
-const someSubInstance = call(
-	someInstance, SomeSubType, ...args);
+### Hooks
 
-// or for array of args
-const someSubInstance = apply(
-	someInstance, SomeSubType, args);
+#### Hook Types
 
-// or for delayed construction
-const someSubInstanceConstructor = 
-	bind( someInstance, SomeSubType );
+- `'preCreation'` - Called before instance creation
+- `'postCreation'` - Called after instance creation
+- `'creationError'` - Called when instance creation throws an error
 
-const someSubInstance = someSubInstanceConstructor(...args);
+#### `type.registerHook(hookType, callback)`
 
+Register a hook on a specific type.
+
+```js
+MyType.registerHook('preCreation', (hookData) => {
+  console.log('Creating:', hookData.TypeName);
+});
 ```
 
-# Asynchronous Constructors
-First of all you should understand what you wish to are doing!
-Then you should understand what you wish. And only after doing so you might use this technic:
+#### `collection.registerHook(hookType, callback)`
+
+Register a hook on a types collection.
 
 ```js
-const AsyncType = define('AsyncType', async function (data) {
-	return Object.assign(this, {
-		data
-	});
+defaultTypes.registerHook('postCreation', (hookData) => {
+  console.log('Created:', hookData.inheritedInstance.constructor.name);
 });
+```
 
-const asyncCall = async function () {
-	const asyncConstructedInstance = await new AsyncType('tada');
-	console.log(asyncConstructedInstance) // { data: "tada" }
-	console.log(asyncConstructedInstance instanceof AsyncType) // true
-};
+#### `collection.registerFlowChecker(callback)`
 
-asyncCall();
+Register a flow checker that runs before hooks.
+
+```js
+defaultTypes.registerFlowChecker((opts) => {
+  console.log('Flow check:', opts.TypeName);
+});
 ```
 
-Also nothing will warn you from doing this for SubTypes:
+#### Hook Data Structure
+
+```typescript
+interface HookData {
+  TypeName: string;              // Constructor name
+  type: TypeDef;                 // The type being constructed
+  args: unknown[];               // Arguments passed to constructor
+  existentInstance: object;      // Parent instance
+  inheritedInstance: object;     // New instance (postCreation only)
+  throwModificationError(error: Error): void;  // Throw error from hook
+}
+```
 
 ```js
-const NestedAsyncType = AsyncType
-	.define('NestedAsyncType', async function (data) {
-		return Object.assign(this, {
-			data
-		});
-	}, {
-		description: 'async of nested'
-	});
+MyType.registerHook('postCreation', (hookData) => {
+  // Throw custom error from hook
+  hookData.throwModificationError(new Error('Custom hook error'));
+});
+```
 
-const nestedAsyncTypeInstance = await new 
-	asyncConstructedInstance.NestedAsyncType('boom');
+**Note:** In preCreation hooks, `existentInstance` refers to the parent; in postCreation hooks, it refers to the instance used for inheritance.
 
-console.log(nestedAsyncTypeInstance instanceof AsyncType) // true
-console.log(nestedAsyncTypeInstance instanceof NestedAsyncType) // true
-console.log(nestedAsyncTypeInstance.description); // 'async of nested'
-```
+---
+
+### Error Handling
 
-Also for the first instance in chain you can do for example inherit from singletone:
+#### Error Types
+
+All mnemonica errors extend `BASE_MNEMONICA_ERROR`:
 
 ```js
-const asyncCalledInstance = await AsyncType
-	.call(process, 'wat');
-// or
-const asyncCalledInstance = await AsyncType
-	.apply(process, ['wat']);
-console.log(asyncCalledInstance) // { data: "wat" }
-console.log(asyncCalledInstance instanceof AsyncType) // true
+const { errors } = require('mnemonica');
+
+// Available error types:
+errors.BASE_MNEMONICA_ERROR
+errors.WRONG_TYPE_DEFINITION
+errors.WRONG_INSTANCE_INVOCATION
+errors.WRONG_MODIFICATION_PATTERN
+errors.ALREADY_DECLARED
+errors.TYPENAME_MUST_BE_A_STRING
+errors.HANDLER_MUST_BE_A_FUNCTION
+errors.WRONG_ARGUMENTS_USED
+errors.WRONG_HOOK_TYPE
+errors.MISSING_HOOK_CALLBACK
+errors.MISSING_CALLBACK_ARGUMENT
+errors.FLOW_CHECKER_REDEFINITION
+errors.OPTIONS_ERROR
+errors.WRONG_STACK_CLEANER
 ```
 
-# Asynch Chain & single await
+#### Exception Instances
 
-Let for example suppose you need the following code:
+When creating exceptions using `instance.exception()`:
 
 ```js
-async (req, res) => {
-	
-	const {
-		email    // : 'async@check.mail',
-		password // : 'some password'
-	} = req.body
-
-	const user = await
-		new UserTypeConstructor({
-			email,
-			password
-		})
-		.UserEntityValidate('valid sign') // sync
-		.WithoutPassword() // sync, rid of password
-	
-	const storagePushResult =
-		await user.AsyncPushToStorage();
-	const storageGetResult =
-		await storagePushResult.AsyncGetStorageResponse();
-	const storageValidateResult =
-		storagePushResult.SyncValidateStorageData()
-	const requestRplyResult = 
-		await StorageValidateResult.AsyncReplyToRequest(res);
-	return requestRplyResult;
-};
+const error = instance.exception(new Error('Original error'));
+
+// Properties:
+error.originalError    // The original error
+error.exceptionReason  // { methodName, ... }
+error.BaseStack        // Base stack trace
+error.parse()          // Parse the exception structure
+error.extract()        // Extract properties from the exception
 ```
 
-Here we have a lot of unnecessary variables. Though we can combine our chain using `.then()` or simpy brakets `(await ...)`, but it will definetely looks weird:
+#### Stack Cleaning
 
 ```js
-async (req, res) => {
-	
-	const {
-		email,    // : 'async@check.mail',
-		password // : 'some password'
-	} = req.body
-
-	const user =
-		await (
-			  (
-		await (
-		await (
-			new UserTypeConstructor({
-				email,
-				password
-			})
-			.UserEntityValidate('valid sign')
-			.WithoutPassword()
-		).AsyncPushToStorage()
-		).AsyncGetStorageResponse()
-		).SyncValidateStorageData()
-		).AsyncReplyToRequest(res);
-};
+const { defineStackCleaner } = require('mnemonica');
+
+// Add regex patterns to clean stack traces
+defineStackCleaner(/node_modules\/some-package/);
 ```
 
-And with using `.then()` of general promises it will look much more badly, even over than "callback hell".
+---
 
-And, if so, starting from `v.0.5.8` we are able to use async chains for async constructors:
+### Symbols & Constants
 
 ```js
-async (req, res) => {
-	
-	const {
-		email,    // : 'async@check.mail',
-		password // : 'some password'
-	} = req.body
-
-	const user =
-		await new UserTypeConstructor({
-				email,
-				password
-			})
-			.UserEntityValidate('valid sign')
-			.WithoutPassword()
-			.AsyncPushToStorage()
-			.AsyncGetStorageResponse()
-			.SyncValidateStorageData()
-			.AsyncReplyToRequest(res);
-};
+const {
+  SymbolParentType,              // Parent type symbol
+  SymbolConstructorName,         // Constructor name symbol
+  SymbolDefaultTypesCollection,  // Default collection symbol
+  SymbolConfig,                  // Config symbol
+  MNEMONICA,                     // Library name
+  MNEMOSYNE                      // Collection identifier
+} = require('mnemonica');
 ```
-So now you don't have to care if this constructor is async or sync and where to put brakets and how many of them. It is enough to type constructor name after the dot and pass necessary arguments. That's it.
 
-## require('util').callbackify
+---
 
-It is important: if we make `util.callbackify` from our instance async creation method, we shall [`.call`](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_objects/Function/call) it then.
+## Configuration Options
 
+Pass options as the third argument to `define()`:
 
+```js
+define('SomeType', function () {}, {
+  strictChain: true,       // Only allow sub-instances from current type
+  blockErrors: true,       // Disallow construction if error in prototype chain
+  submitStack: false,      // Collect stack trace as __stack__ property
+  awaitReturn: true,       // Ensure await new Constructor() returns value
+  ModificationConstructor: fn,  // Custom modification constructor
+  asClass: false           // Force class mode (auto-detected by default)
+});
+```
 
-# Instance Properties
+### Override Default Config for Collection
 
-Also starting from `v0.3.8` the following non enumerable props are availiable from instance itself (`instance.hasOwnProperty(__prop__)`):
+```js
+import { defaultTypes, SymbolConfig } from 'mnemonica';
 
-## Breaking Changes for 0.9.995
+defaultTypes[SymbolConfig].blockErrors = false;
+```
 
-### all props below available from `getProps(instance)` :
+---
 
-## `.__args__`
+## AI Agent Usage Guide
 
-Arguments, used for calling instance creation constructor.
+This section helps AI agents understand and work with mnemonica programmatically.
 
-## `.__type__`
-The definition of instance type.
+### 1. Type Introspection
 
-## `.__parent__`
-If instance is nested, then it is a reference of it's parent.
+Use `utils.parse(instance)` to understand instance structure:
 
-## `.__subtypes__`
-What you can craft from this instance accordingly with it's defined Type, the same as `__type__.subtypes`.
+```js
+const { utils: { parse } } = require('mnemonica');
 
-## `.__collection__`
-Collection of types where `__type__` was defined.
+const parsed = parse(instance);
+// Returns: { name, props, self, proto, joint, parent, constructor }
+```
 
-# `instance.clone`
-Returns cloned instance, with the following condition `instance !== instance.clone`. Cloning includes all the inheritance, with hooks invocations and so on. Therfore cloned instance is not the same as instance, but both made from the same `.__parent__` instance.
+### 2. Safe Property Access
+
+Always use `getProps()` instead of direct property access:
+
+```js
+const { getProps } = require('mnemonica');
 
-_Note_: if you are cloning instance, which has `async Constructor`, you should `await` it;
+const props = getProps(instance);
+// props.__type__, props.__args__, props.__parent__, props.__subtypes__, etc.
+```
 
+### 3. Type Discovery
 
-# **`instance.fork( some, new, args )`**
-Returns forked instance. Behaviour is same as for cloned instance, both made from the same `.__parent__`. But this is a method, not the property, so you can apply another arguments to the constructor.
+```js
+const { defaultTypes } = require('mnemonica');
 
-_Note_: if you are forking instance, which has `async Constructor`, you should `await` it;
+// List all types in default collection
+const typeNames = [...defaultTypes.subtypes.keys()];
 
+// List subtypes of a specific type
+const myType = defaultTypes.MyType;
+const subTypeNames = [...myType.subtypes.keys()];
 
-# Directed Acyclic Graphs
+// Check if a type exists
+const hasType = defaultTypes.lookup('MyType') !== undefined;
+```
 
-## **`instance.fork.call( thisArg, ...args )`**
-## **`instance.fork.apply( thisArg, [args] )`**
-Let assume you nedd [Directed Acyclic Graph](https://en.wikipedia.org/wiki/Directed_acyclic_graph). Then you have to be able to construct it somehow. Starting from `v0.6.1` you can use `fork.call` or `fork.apply` for doing this:
+### 4. Instance Traversal
 
 ```js
-// the following equals
-A.fork.call(B, ...args);
-A.fork.apply(B, [args]);
-A.fork.bind(B)(...args);
+const { getProps } = require('mnemonica');
+
+// Walk up the inheritance chain
+function traverseChain(instance) {
+  const chain = [];
+  let current = instance;
+  
+  while (current) {
+    const props = getProps(current);
+    if (!props) break;
+    
+    chain.push({
+      typeName: props.__type__.TypeName,
+      timestamp: props.__timestamp__,
+      args: props.__args__
+    });
+    
+    current = props.__parent__;
+  }
+  
+  return chain;
+}
 ```
-_Note_: if you are `fork.clone`'ing instance, which has `async Constructor`, you should `await` it;
 
+### 5. Safe Construction Patterns
 
-## mnemonica.utils.merge(A, B, ...args)
-The same as `fork.call` but providing instsnces directly.
+```js
+const { lookup } = require('mnemonica');
 
-_Note_: if you are `merge`'ing instances, where A.constructor is `async Constructor`, you should `await` it;
+// Always check if type exists before construction
+const MyType = lookup('MyType');
+if (MyType) {
+  const instance = new MyType(data);
+}
 
----
+// For nested construction with proper error handling
+try {
+  const subInstance = new instance.SubType(data);
+} catch (error) {
+  // Handle WRONG_MODIFICATION_PATTERN if SubType not defined
+  console.error('Subtype not available:', error.message);
+}
+```
 
-# ESM Support
-Starting from v0.6.8 you can try to import ESM using the following scenario:
+### 6. Analyzing Type Structure
 
 ```js
-import { define, lookup } from 'mnemonica/module';
-```
+const { getProps } = require('mnemonica');
 
-# Config Options
+function analyzeType(typeConstructor) {
+  return {
+    name: typeConstructor.TypeName,
+    isSubType: typeConstructor.isSubType,
+    subTypesCount: typeConstructor.subtypes?.size || 0,
+    hasHooks: Object.keys(typeConstructor.hooks || {}).length > 0,
+    config: typeConstructor.config
+  };
+}
+```
 
-While making `define` we can provide some config data about how instance should be created, default values and descriptions are below:
+### 7. Working with Collections
 
 ```js
-define('SomeType', function () {}, {}, {
+const { createTypesCollection, defaultTypes } = require('mnemonica');
 
-	// shall or not we use strict checking
-	// for creation sub-instances Only from current type
-	// or we might use up-nested sub-instances from chain
-	strictChain: true,
+// Create isolated collection for testing
+const testCollection = createTypesCollection({
+  strictChain: false,
+  blockErrors: false
+});
 
-	// should we use forced errors checking
-	// to make all inherited types errored
-	// if there is an error somewhere in chain
-	// disallow instance construction
-	// if there is an error in prototype chain
-	blockErrors: true,
+// Define types in isolation
+const TestType = testCollection.define('TestType', function () {});
+
+// Register collection-level hooks
+testCollection.registerHook('preCreation', (data) => {
+  console.log('Creating in test collection:', data.TypeName);
+});
+```
+
+---
+
+## Examples
+
+### Asynchronous Constructors
+
+```js
+const AsyncType = define('AsyncType', async function (data) {
+  await someAsyncOperation();
+  return Object.assign(this, { data });
+});
 
-	// if it is necessary to collect stack
-	// as a __stack__ prototype property
-	// during the process of instance creation
-	submitStack: false,
+// Usage
+const asyncInstance = await new AsyncType('tada');
 
-	// await new Constructor()
-	// must return value
-	// optional ./issues/106
-	awaitReturn: true,
+// Nested async types
+const NestedAsync = AsyncType.define('NestedAsync', async function (data) {
+  return Object.assign(this, { nestedData: data });
+});
 
-})
+const nested = await new asyncInstance.NestedAsync('nested');
 ```
 
-Also you can override default config options for Types Collection. For example, after doing so all types that have no own config will fall without any error:
+### Async Chain with Single Await
 
 ```js
-import {
-	defaultTypes,
-	SymbolConfig
-} from 'mnemonica';
+async (req, res) => {
+  const result = await new UserTypeConstructor({
+      email: req.body.email,
+      password: req.body.password
+    })
+    .UserEntityValidate('valid sign')
+    .WithoutPassword()
+    .AsyncPushToStorage()
+    .AsyncGetStorageResponse()
+    .SyncValidateStorageData()
+    .AsyncReplyToRequest(res);
+};
+```
 
-defaultTypes[SymbolConfig].blockErrors = false;
+### Using `call` with Existing Objects
 
+```js
+// Combine with process, window, document, etc.
+const usingProcessAsProto = Singletoned.call(process, {
+  some: 'arguments'
+});
+
+// With React
+import ReactDOM from "react-dom";
+const ReactDOOMed = define("ReactDOOMed", function() {});
+const usingReactAsProto = ReactDOOMed.call(ReactDOM);
 ```
 
+### Directed Acyclic Graphs (DAG)
+
+```js
+// Fork from different parent
+const dagInstance = instanceA.fork.call(instanceB, 'args');
 
-# finally
+// Or use merge utility
+const { utils: { merge } } = require('mnemonica');
+const merged = merge(instanceA, instanceB, 'args');
+```
+
+---
 
-So, now you can craft as much types as you wish, combine them, re-define them and spend much more time playing with them:
+## Epilogue
 
+So, now you can craft as many types as you wish, combine them, re-define them and spend much more time playing with them:
 
 * test : instances & arguments
 * track : moments of creation
 * check : if the order of creation is OK
 * validate : everything, 4 example use sort of TS in runtime
-* and even .parse them using `mnemonica.utils.parse`:
-
-![Inheritance of someSubTypeInstance](https://raw.githubusercontent.com/mythographica/stash/master/img/doc.example.parse.png)
+* and even `.parse` them using `mnemonica.utils.parse`
 
 Good Luck!
+
+---
+
+## License
+
+MIT
+
+Copyright (c) 2019 https://github.com/wentout