@fluidframework/type-factory 2.93.0

package/package.json

@@ -0,0 +1,142 @@
+{
+  "name": "@fluidframework/type-factory",
+  "version": "2.93.0",
+  "description": "Shared types for exposing schema methods and properties to an LLM agent",
+  "homepage": "https://fluidframework.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/microsoft/FluidFramework.git",
+    "directory": "packages/framework/type-factory"
+  },
+  "license": "MIT",
+  "author": "Microsoft and contributors",
+  "sideEffects": false,
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./lib/public.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/public.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./alpha": {
+      "import": {
+        "types": "./lib/alpha.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/alpha.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./internal": {
+      "import": {
+        "types": "./lib/index.d.ts",
+        "default": "./lib/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    }
+  },
+  "main": "lib/index.js",
+  "types": "lib/public.d.ts",
+  "c8": {
+    "all": true,
+    "cache-dir": "nyc/.cache",
+    "exclude": [
+      "src/test/**/*.*ts",
+      "dist/test/**/*.*js",
+      "lib/test/**/*.*js"
+    ],
+    "exclude-after-remap": false,
+    "include": [
+      "src/**/*.*ts",
+      "dist/**/*.*js",
+      "lib/**/*.*js"
+    ],
+    "report-dir": "nyc/report",
+    "reporter": [
+      "cobertura",
+      "html",
+      "text"
+    ],
+    "temp-directory": "nyc/.nyc_output"
+  },
+  "dependencies": {
+    "@fluidframework/telemetry-utils": "~2.93.0"
+  },
+  "devDependencies": {
+    "@arethetypeswrong/cli": "^0.18.2",
+    "@biomejs/biome": "~2.4.5",
+    "@fluid-internal/mocha-test-setup": "~2.93.0",
+    "@fluid-tools/build-cli": "^0.64.0",
+    "@fluidframework/build-common": "^2.0.3",
+    "@fluidframework/build-tools": "^0.64.0",
+    "@fluidframework/eslint-config-fluid": "^9.0.0",
+    "@microsoft/api-extractor": "7.58.1",
+    "@types/mocha": "^10.0.10",
+    "@types/node": "~22.19.17",
+    "c8": "^10.1.3",
+    "concurrently": "^9.2.1",
+    "copyfiles": "^2.4.1",
+    "cross-env": "^10.1.0",
+    "eslint": "~9.39.1",
+    "eslint-config-prettier": "~10.1.8",
+    "jiti": "^2.6.1",
+    "mocha": "^11.7.5",
+    "mocha-multi-reporters": "^1.5.1",
+    "prettier": "~3.6.2",
+    "rimraf": "^6.1.3",
+    "typescript": "~5.4.5"
+  },
+  "typeValidation": {
+    "disabled": true
+  },
+  "scripts": {
+    "api": "fluid-build . --task api",
+    "api-extractor:commonjs": "flub generate entrypoints --resolutionConditions require --outFileLegacyBeta legacy --outDir ./dist",
+    "api-extractor:esnext": "flub generate entrypoints --outFileLegacyBeta legacy --outDir ./lib --node10TypeCompat",
+    "build": "fluid-build . --task build",
+    "build:commonjs": "fluid-build . --task commonjs",
+    "build:compile": "fluid-build . --task compile",
+    "build:docs": "api-extractor run --local",
+    "build:esnext": "tsc --project ./tsconfig.json",
+    "build:test": "npm run build:test:esm && npm run build:test:cjs",
+    "build:test:cjs": "fluid-tsc commonjs --project ./src/test/tsconfig.cjs.json",
+    "build:test:esm": "tsc --project ./src/test/tsconfig.json",
+    "check:are-the-types-wrong": "attw --pack . --profile node16",
+    "check:biome": "biome check .",
+    "check:exports": "concurrently \"npm:check:exports:*\"",
+    "check:exports:bundle-release-tags": "api-extractor run --config api-extractor/api-extractor-lint-bundle.json",
+    "check:exports:cjs:alpha": "api-extractor run --config api-extractor/api-extractor-lint-alpha.cjs.json",
+    "check:exports:cjs:index": "api-extractor run --config api-extractor/api-extractor-lint-index.cjs.json",
+    "check:exports:cjs:public": "api-extractor run --config api-extractor/api-extractor-lint-public.cjs.json",
+    "check:exports:esm:alpha": "api-extractor run --config api-extractor/api-extractor-lint-alpha.esm.json",
+    "check:exports:esm:index": "api-extractor run --config api-extractor/api-extractor-lint-index.esm.json",
+    "check:exports:esm:public": "api-extractor run --config api-extractor/api-extractor-lint-public.esm.json",
+    "check:format": "npm run check:biome",
+    "ci:build:docs": "api-extractor run",
+    "clean": "rimraf --glob dist lib {alpha,beta,internal,legacy}.d.ts \"**/*.tsbuildinfo\" \"**/*.build.log\" _api-extractor-temp nyc",
+    "eslint": "eslint --quiet --format stylish src",
+    "eslint:fix": "eslint --quiet --format stylish src --fix --fix-type problem,suggestion,layout",
+    "format": "npm run format:biome",
+    "format:biome": "biome check . --write",
+    "lint": "fluid-build . --task lint",
+    "lint:fix": "fluid-build . --task eslint:fix --task format",
+    "test": "npm run test:mocha",
+    "test:coverage": "c8 npm test",
+    "test:mocha": "npm run test:mocha:esm && echo skipping cjs to avoid overhead - npm run test:mocha:cjs",
+    "test:mocha:cjs": "cross-env FLUID_TEST_MODULE_SYSTEM=CJS mocha",
+    "test:mocha:esm": "mocha",
+    "test:mocha:verbose": "cross-env FLUID_TEST_VERBOSE=1 npm run test:mocha",
+    "tsc": "fluid-tsc commonjs --project ./tsconfig.cjs.json && copyfiles -f ../../../common/build/build-common/src/cjs/package.json ./dist",
+    "typetests:gen": "flub generate typetests --dir . -v",
+    "typetests:prepare": "flub typetests --dir . --reset --previous --normalize"
+  }
+}

package/src/index.ts

@@ -0,0 +1,57 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/**
+ * Shared types for exposing schema methods and properties to an LLM agent.
+ *
+ * @packageDocumentation
+ */
+
+export {
+	buildFunc,
+	exposeMethodsSymbol,
+	type ExposedMethods,
+	type Arg,
+	type ArgsTuple,
+	type FunctionDef,
+	type MethodKeys,
+	type Ctor,
+	type IExposedMethods,
+} from "./methodBinding.js";
+
+export {
+	exposePropertiesSymbol,
+	type ExposedProperties,
+	type IExposedProperties,
+} from "./propertyBinding.js";
+
+export { typeFactory, isTypeFactoryType } from "./treeAgentTypes.js";
+
+export type {
+	TypeFactoryType,
+	TypeFactoryTypeKind,
+	TypeFactoryString,
+	TypeFactoryNumber,
+	TypeFactoryBoolean,
+	TypeFactoryDate,
+	TypeFactoryVoid,
+	TypeFactoryUndefined,
+	TypeFactoryNull,
+	TypeFactoryUnknown,
+	TypeFactoryArray,
+	TypeFactoryPromise,
+	TypeFactoryObject,
+	TypeFactoryRecord,
+	TypeFactoryMap,
+	TypeFactoryTuple,
+	TypeFactoryUnion,
+	TypeFactoryIntersection,
+	TypeFactoryLiteral,
+	TypeFactoryOptional,
+	TypeFactoryReadonly,
+	TypeFactoryFunction,
+	TypeFactoryFunctionParameter,
+	TypeFactoryInstanceOf,
+} from "./treeAgentTypes.js";

package/src/methodBinding.ts

@@ -0,0 +1,139 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import type { TypeFactoryType } from "./treeAgentTypes.js";
+
+/**
+ * A utility type that extracts the method keys from a given type.
+ * @alpha
+ */
+export type MethodKeys<T> = {
+	[K in keyof T]: T[K] extends (...args: any[]) => any ? K : never;
+};
+
+/**
+ * A type that represents a constructor function.
+ * @alpha
+ */
+export type Ctor<T = any> = new (...args: any[]) => T;
+
+/**
+ * A type that represents a function argument.
+ * @alpha
+ */
+export type Arg<T extends TypeFactoryType = TypeFactoryType> = readonly [
+	name: string,
+	type: T,
+];
+
+/**
+ * A utility type that extracts the argument types from a function definition.
+ * @alpha
+ */
+export type ArgsTuple<T extends readonly Arg[]> = T extends readonly [infer Single extends Arg]
+	? [Single[1]]
+	: T extends readonly [infer Head extends Arg, ...infer Tail extends readonly Arg[]]
+		? [Head[1], ...ArgsTuple<Tail>]
+		: never;
+
+/**
+ * A function definition interface that describes the structure of a function.
+ * @alpha
+ */
+export interface FunctionDef<
+	Args extends readonly Arg[],
+	Return extends TypeFactoryType,
+	Rest extends TypeFactoryType | null = null,
+> {
+	/**
+	 * Optional description of the function.
+	 */
+	description?: string;
+	/**
+	 * The function's parameters.
+	 */
+	args: Args;
+	/**
+	 * Optional rest parameter type.
+	 */
+	rest?: Rest;
+	/**
+	 * The function's return type.
+	 */
+	returns: Return;
+}
+
+/**
+ * A utility function to build a function definition.
+ * @alpha
+ */
+export function buildFunc<
+	const Return extends TypeFactoryType,
+	const Args extends readonly Arg[],
+	const Rest extends TypeFactoryType | null = null,
+>(
+	def: { description?: string; returns: Return; rest?: Rest },
+	...args: Args
+): FunctionDef<Args, Return, Rest> {
+	return {
+		description: def.description,
+		returns: def.returns,
+		args,
+		rest: def.rest,
+	};
+}
+
+/**
+ * An interface for exposing methods of classes to an agent.
+ * @alpha
+ */
+export interface ExposedMethods {
+	/**
+	 * Expose a method with type factory types.
+	 */
+	exposeMethod<
+		const K extends string & keyof MethodKeys<InstanceType<S>>,
+		S extends Ctor & IExposedMethods,
+		Z extends FunctionDef<readonly Arg[], TypeFactoryType, TypeFactoryType | null>,
+	>(constructor: S, methodName: K, tfFunction: Z): void;
+
+	/**
+	 * Expose a method with type factory types.
+	 */
+	expose<
+		const K extends string & keyof MethodKeys<InstanceType<S>>,
+		S extends Ctor & IExposedMethods,
+		Z extends FunctionDef<readonly Arg[], TypeFactoryType, TypeFactoryType | null>,
+	>(constructor: S, methodName: K, tfFunction: Z): void;
+}
+
+/**
+ * A symbol used to expose methods to the LLM.
+ * @alpha
+ */
+export const exposeMethodsSymbol: unique symbol = Symbol("Type factory expose method/symbol");
+
+/**
+ * An interface that classes should implement to expose their methods to the LLM.
+ *
+ * @remarks
+ * The `getExposedMethods` free function will cause the method here to be called on the class passed to it.
+ *
+ * @privateremarks
+ * Implementing this interface correctly seems tricky?
+ * To actually implement it in a way that satisfies TypeScript,
+ * classes need to declare both a static version and an instance version of the method
+ * (the instance one can just delegate to the static one).
+ *
+ * @alpha
+ */
+export interface IExposedMethods {
+	/**
+	 * Static method that exposes methods of this class to an agent.
+	 */
+	[exposeMethodsSymbol](methods: ExposedMethods): void;
+}

package/src/propertyBinding.ts

@@ -0,0 +1,62 @@
+/*!
+ * Copyright (c) Microsoft Corporation and contributors. All rights reserved.
+ * Licensed under the MIT License.
+ */
+
+/* eslint-disable @typescript-eslint/no-explicit-any */
+
+import type { Ctor } from "./methodBinding.js";
+import type { TypeFactoryType } from "./treeAgentTypes.js";
+
+/**
+ * A symbol used to expose properties to the LLM.
+ * @alpha
+ */
+export const exposePropertiesSymbol: unique symbol = Symbol(
+	"Type factory expose property/symbol",
+);
+
+/**
+ * An interface for exposing properties of classes to an agent.
+ * @alpha
+ */
+export interface ExposedProperties {
+	/**
+	 * Expose a property with type factory type and metadata.
+	 */
+	exposeProperty<S extends Ctor, K extends string>(
+		constructor: S,
+		name: K,
+		def: { schema: TypeFactoryType; description?: string; readOnly?: boolean },
+	): void;
+
+	/**
+	 * Expose a property with type factory type (simple form).
+	 */
+	exposeProperty<S extends Ctor, K extends string>(
+		constructor: S,
+		name: K,
+		tfType: TypeFactoryType,
+	): void;
+}
+
+/**
+ * An interface that classes should implement to expose their properties to the LLM.
+ *
+ * @remarks
+ * The `getExposedProperties` free function will cause the method here to be called on the class passed to it.
+ *
+ * @privateremarks
+ * Implementing this interface correctly seems tricky?
+ * To actually implement it in a way that satisfies TypeScript,
+ * classes need to declare both a static version and an instance version of the method
+ * (the instance one can just delegate to the static one).
+ *
+ * @alpha
+ */
+export interface IExposedProperties {
+	/**
+	 * Static method that exposes properties of this class to an agent.
+	 */
+	[exposePropertiesSymbol]?(properties: ExposedProperties): void;
+}