@epsilon-asi/foundation 0.0.6 → 0.0.7

package/LICENSE

@@ -0,0 +1,147 @@
+Epsilon ASI Source-Available License
+Version 1.0
+
+Copyright (c) 2026 Epsilon ASI. All rights reserved.
+
+This license governs use of the software and accompanying files in this
+repository and in the npm packages published from it under the @epsilon-asi
+scope (together, the "Software"). The Software is licensed, not sold. By
+using, copying, modifying, or contributing to the Software you agree to these
+terms. If you do not agree, you may not use the Software.
+
+1. DEFINITIONS
+
+   "Licensor" means Epsilon ASI, the copyright holder.
+   "You" means the individual or legal entity exercising rights under this
+   license.
+   "Application" means a software product or service that You create which
+   uses the Software, or a Modified Version of it, as a component and whose
+   primary purpose and value are not the functionality of the Software itself.
+   "Modified Version" means any copy of the Software that You have altered,
+   extended, or combined with other code, including forks.
+   "Official Repository" means the source code repository for the Software
+   that is designated and controlled by the Licensor.
+   "Contribution" means any modification, addition, or other work that You
+   intentionally submit to the Licensor for inclusion in the Software.
+
+2. GRANT OF RIGHTS
+
+   Subject to the restrictions in Section 3, the Licensor grants You a
+   worldwide, royalty-free, non-exclusive, non-transferable license to:
+
+   a. Install, use, copy, and fork the Software, and create Modified
+      Versions of it, for Your own internal use and for use in Your
+      Applications, including commercial Applications.
+
+   b. Distribute the Software or a Modified Version only as an integrated,
+      non-separable component of Your Applications, and only to the extent
+      necessary for those Applications to run.
+
+   c. Read, study, and modify the source code of the Software for any purpose
+      permitted by this license, including preparing a Contribution.
+
+   d. Maintain a public or private fork of the Official Repository for the
+      purposes in 2(a) and 2(c), provided the fork retains this license and
+      all notices, and is not distributed or offered in any way prohibited by
+      Section 3.
+
+   Sale of Your Applications, including Applications built with the Software
+   or a Modified Version, is expressly permitted. Nothing in this license
+   restricts how You price, license, or distribute Your own Applications.
+
+3. RESTRICTIONS
+
+   Except as expressly permitted in Section 2, You may not:
+
+   a. Distribute, publish, sublicense, rent, lease, lend, sell, or resell the
+      Software or any Modified Version on a standalone basis, as a library,
+      framework, SDK, or developer tool, or under a different name or
+      package scope, whether for a fee or free of charge.
+
+   b. Offer the Software or any Modified Version, or any product or service
+      whose primary purpose and value are the functionality of the Software,
+      to third parties as a hosted, managed, or embedded service, or as a
+      product that competes with the Software or with any product the
+      Licensor provides using the Software.
+
+   c. Remove, obscure, or alter any copyright, license, or attribution notice
+      in the Software or any Modified Version, or relicense the Software or
+      any Modified Version under different terms.
+
+   d. Use the Licensor's names, logos, or trademarks except to identify the
+      Software as the origin of a component of Your Application, or to
+      describe a fork accurately as derived from the Software.
+
+   Where the Licensor has published the Software under a different license
+   for a specific version, that license governs that version.
+
+4. CONTRIBUTIONS
+
+   a. By submitting a Contribution You grant the Licensor a perpetual,
+      worldwide, irrevocable, royalty-free, non-exclusive license, with the
+      right to sublicense, to use, reproduce, modify, distribute, publicly
+      display, and otherwise exploit the Contribution as part of the Software
+      or otherwise, under this license or any other terms the Licensor
+      chooses.
+
+   b. You represent that You have the right to grant the license in 4(a),
+      that the Contribution is Your original work or that You otherwise hold
+      the rights necessary to submit it, and that it does not knowingly
+      violate any third-party rights.
+
+   c. Once a Contribution is accepted into the Official Repository it becomes
+      part of the Software and is governed by this license. You retain
+      copyright in Your Contribution but may not exercise rights in the
+      combined Software beyond those granted in Section 2.
+
+   d. The Licensor is under no obligation to accept any Contribution.
+
+5. OWNERSHIP
+
+   The Software is protected by copyright and other intellectual property
+   laws. The Licensor retains all right, title, and interest in and to the
+   Software not expressly granted to You in this license. You own the
+   copyright in the original portions of Your Modified Versions, subject to
+   the Licensor's rights in the underlying Software and the restrictions in
+   Section 3.
+
+6. TERMINATION
+
+   This license terminates automatically if You breach any of its terms. On
+   termination You must stop using and distributing the Software and any
+   Modified Version and destroy all copies in Your possession, except that
+   Applications already distributed to end users in compliance with Section
+   2(b) before termination may continue to be used by those end users.
+   Sections 4, 5, 7, 8, and 9 survive termination.
+
+7. DISCLAIMER OF WARRANTY
+
+   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+   IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+   FITNESS FOR A PARTICULAR PURPOSE, TITLE, AND NON-INFRINGEMENT.
+
+8. LIMITATION OF LIABILITY
+
+   IN NO EVENT SHALL THE LICENSOR BE LIABLE FOR ANY CLAIM, DAMAGES, OR OTHER
+   LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE, ARISING
+   FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
+   DEALINGS IN THE SOFTWARE, INCLUDING INDIRECT, INCIDENTAL, SPECIAL, OR
+   CONSEQUENTIAL DAMAGES OR LOSS OF PROFITS, EVEN IF ADVISED OF THE
+   POSSIBILITY OF SUCH DAMAGES.
+
+9. GENERAL
+
+   This license is governed by the laws of [STATE / COUNTRY], without regard
+   to its conflict-of-law rules. If any provision is held unenforceable, the
+   remainder of the license remains in effect. This license is the entire
+   agreement between You and the Licensor concerning the Software and
+   supersedes any prior understanding. The Licensor may publish revised
+   versions of this license; each version of the Software is governed by the
+   license text distributed with it.
+
+This is not an open-source license as defined by the Open Source Initiative.
+It is a source-available license: the source code is public, and You may use
+it, fork it, modify it, build and sell products with it, and contribute to it
+as described above. You may not resell it, redistribute it or a Modified
+Version as a standalone library or service, or offer it as a competing
+product.

package/build/decorators/factory/clone.d.ts

@@ -1,3 +1,3 @@
-export declare function cloneDeep<T>(value: T, seen?: WeakMap<object, unknown>): T;
+export declare function cloneDeep<T>(value: T, seen?: WeakMap<object, unknown>, created?: object[]): T;
 export declare function deepFreeze<T>(value: T, seen?: WeakSet<object>): T;
 export declare function immutableClone<T>(value: T): T;

package/build/decorators/factory/clone.js

@@ -6,7 +6,7 @@ exports.immutableClone = immutableClone;
 function isObjectLike(value) {
     return (typeof value === 'object' && value !== null) || typeof value === 'function';
 }
-function cloneDeep(value, seen = new WeakMap()) {
+function cloneDeep(value, seen = new WeakMap(), created) {
     if (!isObjectLike(value))
         return value;
     if (typeof value === 'function')
@@ -15,42 +15,50 @@ function cloneDeep(value, seen = new WeakMap()) {
     if (existing !== undefined)
         return existing;
     if (value instanceof Date) {
-        return new Date(value.getTime());
+        const cloned = new Date(value.getTime());
+        created === null || created === void 0 ? void 0 : created.push(cloned);
+        return cloned;
     }
     if (value instanceof RegExp) {
-        return new RegExp(value.source, value.flags);
+        const cloned = new RegExp(value.source, value.flags);
+        created === null || created === void 0 ? void 0 : created.push(cloned);
+        return cloned;
     }
     if (value instanceof Map) {
         const cloned = new Map();
         seen.set(value, cloned);
+        created === null || created === void 0 ? void 0 : created.push(cloned);
         for (const [key, mapValue] of value.entries()) {
-            cloned.set(cloneDeep(key, seen), cloneDeep(mapValue, seen));
+            cloned.set(cloneDeep(key, seen, created), cloneDeep(mapValue, seen, created));
         }
         return cloned;
     }
     if (value instanceof Set) {
         const cloned = new Set();
         seen.set(value, cloned);
+        created === null || created === void 0 ? void 0 : created.push(cloned);
         for (const setValue of value.values()) {
-            cloned.add(cloneDeep(setValue, seen));
+            cloned.add(cloneDeep(setValue, seen, created));
         }
         return cloned;
     }
     if (Array.isArray(value)) {
         const cloned = [];
         seen.set(value, cloned);
+        created === null || created === void 0 ? void 0 : created.push(cloned);
         for (const item of value)
-            cloned.push(cloneDeep(item, seen));
+            cloned.push(cloneDeep(item, seen, created));
         return cloned;
     }
     const cloned = Object.create(Object.getPrototypeOf(value));
     seen.set(value, cloned);
+    created === null || created === void 0 ? void 0 : created.push(cloned);
     for (const key of Reflect.ownKeys(value)) {
         const descriptor = Object.getOwnPropertyDescriptor(value, key);
         if (descriptor === undefined)
             continue;
         if ('value' in descriptor) {
-            descriptor.value = cloneDeep(descriptor.value, seen);
+            descriptor.value = cloneDeep(descriptor.value, seen, created);
         }
         Object.defineProperty(cloned, key, descriptor);
     }
@@ -81,5 +89,12 @@ function deepFreeze(value, seen = new WeakSet()) {
     return Object.freeze(value);
 }
 function immutableClone(value) {
-    return deepFreeze(cloneDeep(value));
+    // Freeze only the objects cloneDeep made. Values it shares by reference (functions, and anything
+    // reachable from them) still belong to the caller. A shallow freeze of each is enough: every
+    // object cloneDeep made is in `created`, and no getter is invoked along the way.
+    const created = [];
+    const cloned = cloneDeep(value, new WeakMap(), created);
+    for (const node of created)
+        Object.freeze(node);
+    return cloned;
 }

package/build/decorators/factory/examples/crud.js

@@ -101,7 +101,8 @@ let UserCrud = (() => {
 })();
 exports.UserCrud = UserCrud;
 function buildCrudSummary() {
-    const snapshot = registry.read(UserCrud);
+    const testUser = new UserCrud();
+    const snapshot = registry.read(testUser);
     const resource = snapshot.firstClass('resource');
     if (resource === undefined)
         throw new Error('Missing @Resource metadata.');
@@ -118,3 +119,4 @@ function buildCrudSummary() {
         }),
     };
 }
+console.log(buildCrudSummary());

package/build/decorators/factory/types.d.ts

@@ -52,20 +52,20 @@ export interface DecorationRecord {
     private: boolean;
     order: number;
 }
-export interface RegistryMetadataSnapshot {
+export interface RegistryMetadataSnapshot<DecoratorName extends string = string> {
     readonly all: readonly DecorationRecord[];
     readonly classes: readonly DecorationRecord[];
     readonly properties: readonly DecorationRecord[];
     readonly methods: readonly DecorationRecord[];
     readonly accessors: readonly DecorationRecord[];
-    firstClass(decorator: string): DecorationRecord | undefined;
-    classRecords(decorator?: string): readonly DecorationRecord[];
-    propertyRecords(decorator?: string): readonly DecorationRecord[];
-    methodRecords(decorator?: string): readonly DecorationRecord[];
-    accessorRecords(decorator?: string): readonly DecorationRecord[];
-    propertyMap(decorator?: string): ReadonlyMap<string | symbol, readonly DecorationRecord[]>;
-    methodMap(decorator?: string): ReadonlyMap<string | symbol, readonly DecorationRecord[]>;
-    accessorMap(decorator?: string): ReadonlyMap<string | symbol, readonly DecorationRecord[]>;
+    firstClass(decorator: DecoratorName): DecorationRecord | undefined;
+    classRecords(decorator?: DecoratorName): readonly DecorationRecord[];
+    propertyRecords(decorator?: DecoratorName): readonly DecorationRecord[];
+    methodRecords(decorator?: DecoratorName): readonly DecorationRecord[];
+    accessorRecords(decorator?: DecoratorName): readonly DecorationRecord[];
+    propertyMap(decorator?: DecoratorName): ReadonlyMap<string | symbol, readonly DecorationRecord[]>;
+    methodMap(decorator?: DecoratorName): ReadonlyMap<string | symbol, readonly DecorationRecord[]>;
+    accessorMap(decorator?: DecoratorName): ReadonlyMap<string | symbol, readonly DecorationRecord[]>;
 }
 export interface CreateDecoratorRegistryOptions {
     namespace?: string;

package/build/decorators/types/errors.d.ts

@@ -0,0 +1,12 @@
+export interface TypeRegistryErrorDetails {
+    typeName?: string;
+    field?: string;
+    extension?: string;
+    cause?: unknown;
+}
+export declare class TypeRegistryError extends Error {
+    readonly typeName?: string;
+    readonly field?: string;
+    readonly extension?: string;
+    constructor(message: string, details?: TypeRegistryErrorDetails);
+}

package/build/decorators/types/errors.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypeRegistryError = void 0;
+class TypeRegistryError extends Error {
+    constructor(message, details = {}) {
+        super(message, details.cause !== undefined ? { cause: details.cause } : undefined);
+        this.name = 'TypeRegistryError';
+        this.typeName = details.typeName;
+        this.field = details.field;
+        this.extension = details.extension;
+    }
+}
+exports.TypeRegistryError = TypeRegistryError;

package/build/decorators/types/extension.d.ts

@@ -0,0 +1,7 @@
+import type { z } from 'zod/v4';
+import type { TypeExtension } from './types';
+/**
+ * Declares a type extension. Exists for inference: the key stays a literal and the
+ * `decorators` callback is typed by the `field` and `type` option schemas.
+ */
+export declare function defineTypeExtension<TKey extends string, TField extends z.ZodType | undefined = undefined, TType extends z.ZodType | undefined = undefined, TDecorators extends object = {}>(extension: TypeExtension<TKey, TField, TType, TDecorators>): TypeExtension<TKey, TField, TType, TDecorators>;

package/build/decorators/types/extension.js

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defineTypeExtension = defineTypeExtension;
+/**
+ * Declares a type extension. Exists for inference: the key stays a literal and the
+ * `decorators` callback is typed by the `field` and `type` option schemas.
+ */
+function defineTypeExtension(extension) {
+    return Object.freeze(Object.assign({}, extension));
+}

package/build/decorators/types/index.d.ts

@@ -0,0 +1,5 @@
+export { createTypeRegistry } from './typeRegistry';
+export { defineTypeExtension } from './extension';
+export { TypeRegistryError } from './errors';
+export type { TypeRegistryErrorDetails } from './errors';
+export * from './types';

package/build/decorators/types/index.js

@@ -0,0 +1,24 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __exportStar = (this && this.__exportStar) || function(m, exports) {
+    for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.TypeRegistryError = exports.defineTypeExtension = exports.createTypeRegistry = void 0;
+var typeRegistry_1 = require("./typeRegistry");
+Object.defineProperty(exports, "createTypeRegistry", { enumerable: true, get: function () { return typeRegistry_1.createTypeRegistry; } });
+var extension_1 = require("./extension");
+Object.defineProperty(exports, "defineTypeExtension", { enumerable: true, get: function () { return extension_1.defineTypeExtension; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "TypeRegistryError", { enumerable: true, get: function () { return errors_1.TypeRegistryError; } });
+__exportStar(require("./types"), exports);

package/build/decorators/types/typeRegistry.d.ts

@@ -0,0 +1,2 @@
+import type { CreateTypeRegistryOptions, TypeRegistry } from './types';
+export declare function createTypeRegistry(options?: CreateTypeRegistryOptions): TypeRegistry;