mnemonica 1.0.6 → 1.0.8

package/src/index.ts

@@ -14,7 +14,6 @@ import type {
 	TypeClass,
 	TypeAbsorber,
 	MnemonicaModule,
-	TypeConstructor,
 	InstanceResult,
 	Merge
 } from './types';
@@ -26,9 +25,37 @@ export const {
 } = TypesUtils;
 
 export type {
-	IDEF, TypeConstructor, _Internal_TC_, Proto, ProtoFlat,
+	IDEF, TypeConstructor, TypeConstructorBase,
+	InstanceOfTypeRegistry, LiteralKeysOf, ParentPath, PathOfInstance,
+	AllParentPrefixes, ParentPathOfInstance,
+	_Internal_TC_, Proto, ProtoFlat,
 	hooksOpts, hook, hooksTypes, TypesCollection
 } from './types';
+
+/**
+ * Type-safe registry for mnemonica types.
+ *
+ * This interface starts empty. Application code or `@mnemonica/tactica`
+ * augments it through TypeScript module declaration merging:
+ *
+ * ```ts
+ * declare module 'mnemonica' {
+ *   interface TypeRegistry {
+ *     'MyType': TypeConstructor<MyTypeInstance>;
+ *     'MyType.SubType': TypeConstructor<SubTypeInstance>;
+ *   }
+ * }
+ * ```
+ *
+ * Once augmented, `lookup('MyType')` and `utils.parent(instance, 'MyType')`
+ * resolve keys against this registry. Unaugmented keys fall back to the broad
+ * `TypeClass | undefined` return type.
+ */
+export interface TypeRegistry {
+	// Intentionally empty. Augment this interface via declaration merging
+	// (hand-written or generated by @mnemonica/tactica) to enable typed
+	// utilities like lookup() and parent().
+}
 export {
 	getProps, setProps 
 } from './api/types/Props';
@@ -78,7 +105,12 @@ export const define = function <
 	return defineResult;
 } as TypeAbsorber;
 
-export const lookup = function (
+export function lookup<const K extends keyof TypeRegistry>(
+	this: unknown,
+	TypeNestedPath: K
+): TypeRegistry[K];
+export function lookup(this: unknown, TypeNestedPath: string): TypeClass | undefined;
+export function lookup(
 	this: unknown,
 	TypeNestedPath: string
 ): TypeClass | undefined {
@@ -86,58 +118,8 @@ export const lookup = function (
 	// Type assertion needed because TypesCollectionProxy is a Proxy
 	const lookupResult = (types as { lookup: (path: string) => TypeClass | undefined }).lookup(TypeNestedPath);
 	return lookupResult;
-};
-
-/**
- * Default TypeRegistry interface - augment this in your project via
- * TypeScript declaration merging. The augmentation can be hand-written
- * in a .d.ts file (small projects) or generated by @mnemonica/tactica.
- *
- * Uses `TypeConstructor<never>` as the index value type to enforce
- * augmentation: without it, any key lookup resolves to a useless type
- * because `TypeConstructor<never>` is not assignable to concrete types.
- *
- * Example (in a hand-written .d.ts, or generated by tactica in
- * .tactica/registry.ts):
- *   declare module 'mnemonica' {
- *     interface TypeRegistry {
- *       'MyType': new (...args: unknown[]) => MyTypeInstance;
- *     }
- *   }
- *
- * See docs/typed-lookup.md for both paths side by side.
- */
-export interface TypeRegistry {
-	[key: string]: TypeConstructor<never>;
 }
 
-/**
- * Type-safe lookup function. Requires a TypeRegistry augmentation —
- * hand-written in a .d.ts (small projects) or generated by
- * @mnemonica/tactica (auto-synced from your define() calls).
- *
- * At runtime this delegates to lookup(). The type safety is
- * compile-time only: TypeScript resolves the key against the augmented
- * TypeRegistry and returns the constructor's type signature.
- *
- * Usage (once TypeRegistry is augmented):
- *   const SomeType = lookupTyped('SomeType');
- *   const instance = new SomeType({ ... }); // Full type safety!
- *
- * See docs/typed-lookup.md for both augmentation paths side by side.
- */
-export const lookupTyped = function <
-	const K extends keyof TypeRegistry
->(
-	this: unknown,
-	TypeNestedPath: K
-): TypeRegistry[K]  {
-	const types = checkThis(this) ? defaultTypes : this || defaultTypes;
-	const lookupResult = (types as { lookup: (path: string) => unknown })
-		.lookup(TypeNestedPath as string) as TypeRegistry[K];
-	return lookupResult;
-};
-
 
 const $run = function <E extends object, T extends object, S extends Proto<E, T>>(
 	entity: E,

package/src/types/index.ts

@@ -1,6 +1,8 @@
 'use strict';
 /* eslint no-unused-vars: "off" */
 
+import type { TypeRegistry } from '../index';
+
 // Props type for getProps/setProps
 export type PropsType = Record<string, unknown>;
 
@@ -78,6 +80,79 @@ export interface _Internal_TC_<ConstructorInstance extends object> {
  */
 export type TypeConstructor<ConstructorInstance extends object> = _Internal_TC_<ConstructorInstance>;
 
+/**
+ * Minimal constructor shape used for the TypeRegistry index signature.
+ * It accepts any mnemonica-compatible constructor, but deliberately returns
+ * `object` so unaugmented registry lookups are not useful without an explicit
+ * per-key constructor type.
+ */
+export interface TypeConstructorBase {
+	new (...args: unknown[]): object;
+}
+
+/**
+ * Instance type produced by a TypeRegistry constructor.
+ */
+export type InstanceOfTypeRegistry<K extends keyof TypeRegistry> =
+	TypeRegistry[K] extends new (...args: unknown[]) => infer R ? R : never;
+
+
+/**
+ * Extract only the literal string keys of a type, filtering out generic
+ * index signatures. This lets us iterate over augmented TypeRegistry keys
+ * without picking up the `[key: string]` signature.
+ */
+export type LiteralKeysOf<T> = keyof T extends infer K
+	? K extends string
+		? string extends K ? never : K
+		: never
+	: never;
+
+/**
+ * Given a dotted TypeRegistry key, extract the parent path.
+ * `ParentPath<'A.B.C'>` → `'A.B'`.
+ */
+export type ParentPath<K extends string> =
+	K extends `${infer P}.${string}` ? P : never;
+
+/**
+ * Given a dotted TypeRegistry key, return the union of all ancestor prefixes.
+ * `AllParentPrefixes<'A.B.C'>` → `'A' | 'A.B'`.
+ */
+export type AllParentPrefixes<K extends string> =
+	K extends `${infer P}.${string}` ? P | AllParentPrefixes<P> : never;
+
+/**
+ * Given a parent path, return the union of TypeRegistry keys that are direct
+ * or indirect children of that path.
+ */
+export type ChildKeysOf<P extends string> = {
+	[K in keyof TypeRegistry]: K extends `${P}.${string}` ? K : never
+}[keyof TypeRegistry];
+
+/**
+ * Given an instance type, find the TypeRegistry key(s) whose constructor
+ * returns that instance type. This inverts the registry at the type level
+ * so utilities like `parent()` can derive an instance's path from its
+ * type alone.
+ */
+export type PathOfInstance<T extends object> = {
+	[K in LiteralKeysOf<TypeRegistry>]: TypeRegistry[K] extends new (...args: unknown[]) => infer R
+		? T extends R ? K : never
+		: never
+}[LiteralKeysOf<TypeRegistry>];
+
+/**
+ * Given an instance type, return the union of TypeRegistry paths that are
+ * valid parent lookups for that instance. Root types produce `never` because
+ * they have no parent path.
+ */
+export type ParentPathOfInstance<T extends object> = {
+	[K in LiteralKeysOf<TypeRegistry>]: TypeRegistry[K] extends new (...args: unknown[]) => infer R
+		? T extends R ? AllParentPrefixes<K> : never
+		: never
+}[LiteralKeysOf<TypeRegistry>];
+
 // Hook types
 export type hooksTypes = 'preCreation' | 'postCreation' | 'creationError';
 
@@ -288,6 +363,9 @@ export interface MnemonicaInstance<T extends object = object> {
 	pick<K extends keyof T>(...keys: (K | K[])[]): { [P in K]: T[P] } & {};
 	pick(...keys: string[]): Record<string, unknown>;
 	parent(): object | undefined;
+	parent<K extends ParentPathOfInstance<this> & string>(
+		constructorLookupPath: K
+	): InstanceOfTypeRegistry<K> | undefined;
 	parent(constructorLookupPath: string): object | undefined;
 	readonly clone: this;
 	fork(...forkArgs: unknown[]): this;
@@ -507,7 +585,12 @@ export interface UtilsCollection {
 		...args: unknown[]
 	): InstanceResult<Merge<B, A>>;
 	parse<T extends object>(self: T): Parsed<T>;
-	parent<T extends object>(instance: T, path?: string): object | undefined;
+	parent<T extends object>(instance: T): object | undefined;
+	parent<T extends object, K extends ParentPathOfInstance<T> & string>(
+		instance: T,
+		path: K
+	): InstanceOfTypeRegistry<K> | undefined;
+	parent<T extends object>(instance: T, path: string): object | undefined;
 	toJSON<T extends object>(instance: T): string;
 	[key: string]: CallableFunction;
 }
@@ -516,7 +599,10 @@ export interface UtilsCollection {
 export interface MnemonicaModule {
 	// Core functions
 	define: TypeAbsorber;
-	lookup: (TypeNestedPath: string) => TypeClass | undefined;
+	lookup: {
+		(TypeNestedPath: string): TypeClass | undefined;
+		<const K extends keyof TypeRegistry>(TypeNestedPath: K): TypeRegistry[K];
+	};
 	apply: ApplyFunction;
 	call: CallFunction;
 	bind: BindFunction;

package/src/utils/parent.ts

@@ -1,5 +1,10 @@
 'use strict';
 
+import type {
+	InstanceOfTypeRegistry,
+	ParentPathOfInstance
+} from '../types';
+
 import { ErrorsTypes } from '../descriptors/errors';
 const { WRONG_INSTANCE_INVOCATION } = ErrorsTypes;
 
@@ -10,7 +15,13 @@ import {
 // seek for firts parent instance
 // of instance prototype chain
 // with constructors of path
-export const parent = <T extends object>( instance: T, path?: string ): object | undefined => {
+export function parent <T extends object> (instance: T): object | undefined;
+export function parent <T extends object, K extends ParentPathOfInstance<T> & string> (
+	instance: T,
+	path: K
+): InstanceOfTypeRegistry<K> | undefined;
+export function parent (instance: object, path: string): object | undefined;
+export function parent <T extends object> (instance: T, path?: string): object | undefined {
 
 	// at this situation this check is enough
 	if ( instance !== Object( instance ) ) {
@@ -37,4 +48,4 @@ export const parent = <T extends object>( instance: T, path?: string ): object |
 		p : parent( p as object, path );
 	return result;
 
-};
+}