@fluojs/core 1.0.0-beta.1

package/dist/types.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A constructable type that yields `T`.
+ *
+ * The `any[]` parameter list is intentional — this type models "some class that
+ * produces T" for DI token resolution, not a safely-callable constructor
+ * signature. Using `unknown[]` would break assignability for any class with
+ * typed constructor parameters (variance rules make `[string]` incompatible
+ * with `unknown[]` in `new` signatures). Every major DI framework (NestJS,
+ * Angular, tsyringe, inversify) uses the same pattern for the same reason.
+ */
+export type Constructor<T = unknown> = new (...args: any[]) => T;
+/**
+ * Public dependency token accepted by Fluo containers, decorators, and module metadata.
+ *
+ * Class constructors act as self-describing tokens, while strings and symbols support
+ * interface-like or cross-package registrations where no concrete class should leak.
+ */
+export type Token<T = unknown> = string | symbol | Constructor<T>;
+/**
+ * Value that may be returned synchronously or wrapped in a `Promise`.
+ *
+ * This keeps factory helpers and lifecycle hooks flexible without forcing every caller to
+ * treat the operation as asynchronous.
+ */
+export type MaybePromise<T> = T | Promise<T>;
+/**
+ * Factory configuration for module helpers that compute options during bootstrap.
+ *
+ * @typeParam T Resolved options shape returned to the module factory.
+ */
+export interface AsyncModuleOptions<T> {
+    inject?: Token[];
+    useFactory: (...deps: unknown[]) => MaybePromise<T>;
+}
+/**
+ * Metadata property name supported by Fluo's shared metadata stores.
+ */
+export type MetadataPropertyKey = string | symbol;
+/**
+ * Canonical request-data origins used by packages that describe how metadata values are bound.
+ */
+export type MetadataSource = 'path' | 'query' | 'header' | 'cookie' | 'body';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,MAAM,MAAM,WAAW,CAAC,CAAC,GAAG,OAAO,IAAI,KAAK,GAAG,IAAI,EAAE,GAAG,EAAE,KAAK,CAAC,CAAC;AAEjE;;;;;GAKG;AACH,MAAM,MAAM,KAAK,CAAC,CAAC,GAAG,OAAO,IAAI,MAAM,GAAG,MAAM,GAAG,WAAW,CAAC,CAAC,CAAC,CAAC;AAElE;;;;;GAKG;AACH,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,GAAG,OAAO,CAAC,CAAC,CAAC,CAAC;AAE7C;;;;GAIG;AACH,MAAM,WAAW,kBAAkB,CAAC,CAAC;IACnC,MAAM,CAAC,EAAE,KAAK,EAAE,CAAC;IACjB,UAAU,EAAE,CAAC,GAAG,IAAI,EAAE,OAAO,EAAE,KAAK,YAAY,CAAC,CAAC,CAAC,CAAC;CACrD;AAED;;GAEG;AACH,MAAM,MAAM,mBAAmB,GAAG,MAAM,GAAG,MAAM,CAAC;AAElD;;GAEG;AACH,MAAM,MAAM,cAAc,GAAG,MAAM,GAAG,OAAO,GAAG,QAAQ,GAAG,QAAQ,GAAG,MAAM,CAAC"}

package/dist/types.js

@@ -0,0 +1 @@
+export {};

package/dist/utils.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Clones a value through `structuredClone()` and falls back to the hardened internal clone path when needed.
+ *
+ * @param value Value to clone.
+ * @returns A cloned value produced by `structuredClone()` when available, or `fallbackClone()` when the runtime clone fails.
+ */
+export declare function cloneWithFallback<T>(value: T): T;
+/**
+ * Creates a best-effort deep clone for runtimes where `structuredClone()` is not available or throws.
+ *
+ * Supported fallback shapes include arrays, dates, regular expressions, maps, sets, typed arrays,
+ * array buffers, plain objects, and custom prototype-based instances with symbol-keyed properties
+ * and circular references preserved.
+ *
+ * @param value Value to clone through the fallback path.
+ * @returns A deep clone for supported runtime shapes, or the original value for primitives/functions.
+ */
+export declare function fallbackClone<T>(value: T): T;
+//# sourceMappingURL=utils.d.ts.map

package/dist/utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"utils.d.ts","sourceRoot":"","sources":["../src/utils.ts"],"names":[],"mappings":"AAmGA;;;;;GAKG;AACH,wBAAgB,iBAAiB,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAMhD;AAED;;;;;;;;;GASG;AACH,wBAAgB,aAAa,CAAC,CAAC,EAAE,KAAK,EAAE,CAAC,GAAG,CAAC,CAE5C"}

package/dist/utils.js

@@ -0,0 +1,103 @@
+function cloneIntoDescriptorValue(descriptor, seen) {
+  if (!('value' in descriptor)) {
+    return descriptor;
+  }
+  return {
+    ...descriptor,
+    value: cloneFallbackValue(descriptor.value, seen)
+  };
+}
+function cloneFallbackValue(value, seen) {
+  if (typeof value !== 'object' || value === null) {
+    return value;
+  }
+  const existing = seen.get(value);
+  if (existing) {
+    return existing;
+  }
+  if (Array.isArray(value)) {
+    const cloned = [];
+    seen.set(value, cloned);
+    cloned.push(...value.map(item => cloneFallbackValue(item, seen)));
+    return cloned;
+  }
+  if (value instanceof Date) {
+    const cloned = new Date(value.getTime());
+    seen.set(value, cloned);
+    return cloned;
+  }
+  if (value instanceof RegExp) {
+    const cloned = new RegExp(value.source, value.flags);
+    cloned.lastIndex = value.lastIndex;
+    seen.set(value, cloned);
+    return cloned;
+  }
+  if (value instanceof Map) {
+    const cloned = new Map();
+    seen.set(value, cloned);
+    for (const [key, entryValue] of value.entries()) {
+      cloned.set(cloneFallbackValue(key, seen), cloneFallbackValue(entryValue, seen));
+    }
+    return cloned;
+  }
+  if (value instanceof Set) {
+    const cloned = new Set();
+    seen.set(value, cloned);
+    for (const entryValue of value.values()) {
+      cloned.add(cloneFallbackValue(entryValue, seen));
+    }
+    return cloned;
+  }
+  if (value instanceof DataView) {
+    const cloned = new DataView(value.buffer.slice(value.byteOffset, value.byteOffset + value.byteLength));
+    seen.set(value, cloned);
+    return cloned;
+  }
+  if (ArrayBuffer.isView(value)) {
+    const cloned = new value.constructor(value);
+    seen.set(value, cloned);
+    return cloned;
+  }
+  if (value instanceof ArrayBuffer) {
+    const cloned = value.slice(0);
+    seen.set(value, cloned);
+    return cloned;
+  }
+  const cloned = Object.create(Object.getPrototypeOf(value));
+  seen.set(value, cloned);
+  for (const key of Reflect.ownKeys(value)) {
+    const descriptor = Object.getOwnPropertyDescriptor(value, key);
+    if (descriptor) {
+      Object.defineProperty(cloned, key, cloneIntoDescriptorValue(descriptor, seen));
+    }
+  }
+  return cloned;
+}
+
+/**
+ * Clones a value through `structuredClone()` and falls back to the hardened internal clone path when needed.
+ *
+ * @param value Value to clone.
+ * @returns A cloned value produced by `structuredClone()` when available, or `fallbackClone()` when the runtime clone fails.
+ */
+export function cloneWithFallback(value) {
+  try {
+    return structuredClone(value);
+  } catch {
+    return fallbackClone(value);
+  }
+}
+
+/**
+ * Creates a best-effort deep clone for runtimes where `structuredClone()` is not available or throws.
+ *
+ * Supported fallback shapes include arrays, dates, regular expressions, maps, sets, typed arrays,
+ * array buffers, plain objects, and custom prototype-based instances with symbol-keyed properties
+ * and circular references preserved.
+ *
+ * @param value Value to clone through the fallback path.
+ * @returns A deep clone for supported runtime shapes, or the original value for primitives/functions.
+ */
+export function fallbackClone(value) {
+  return cloneFallbackValue(value, new WeakMap());
+}

package/package.json

@@ -0,0 +1,52 @@
+{
+  "name": "@fluojs/core",
+  "description": "Shared contracts, decorators, and metadata helpers that form the foundation of every Fluo package.",
+  "keywords": [
+    "fluo",
+    "core",
+    "decorators",
+    "metadata",
+    "types",
+    "foundation"
+  ],
+  "version": "1.0.0-beta.1",
+  "private": false,
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/fluojs/fluo.git",
+    "directory": "packages/core"
+  },
+  "engines": {
+    "node": ">=20.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./internal": {
+      "types": "./dist/internal.d.ts",
+      "import": "./dist/internal.js"
+    }
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "vitest": "^3.2.4"
+  },
+  "scripts": {
+    "prebuild": "node ../../tooling/scripts/clean-dist.mjs",
+    "build": "pnpm exec babel src --extensions .ts --ignore 'src/**/*.test.ts' --out-dir dist --config-file ../../tooling/babel/babel.config.cjs && pnpm exec tsc -p tsconfig.build.json",
+    "typecheck": "pnpm exec tsc -p tsconfig.json --noEmit",
+    "test": "pnpm exec vitest run -c vitest.config.ts",
+    "test:watch": "pnpm exec vitest -c vitest.config.ts"
+  }
+}