@openfairygui/functions 0.1.1 → 0.2.0-alpha.1

package/README.md

@@ -1,6 +1,6 @@
 # @openfairygui/functions
 
-Composable authoring and publish functions built on top of `@openfairygui/core`.
+Composable authoring workflows and thin application seams built on top of `@openfairygui/core`.
 
 ## Install
 
@@ -21,6 +21,41 @@ const report = inspect(doc);
 await doc.transform(publish({ output: './release' }));
 ```
 
+## Phase A UAM authoring seam
+
+`@openfairygui/functions` also exposes a thin stateless wrapper over the Phase A UAM
+transaction contract from `@openfairygui/core`.
+
+This seam:
+
+- accepts `UamProject` + `UamTransactionOperation[]`
+- returns structured app-level success / failure results
+- does not expose `Document`
+- does not define a second selector / operation grammar
+- does not wrap `publish` or `restore`
+
+```ts
+import {
+	type UamProject,
+	type UamTransactionOperation,
+} from '@openfairygui/core';
+import { applyUamTransactionApp } from '@openfairygui/functions';
+
+const project: UamProject = /* ... */;
+const operations: UamTransactionOperation[] = [
+	{
+		kind: 'renameResource',
+		selector: { packageId: 'pkg001', resourceId: 'img001' },
+		newName: 'renamed.png',
+	},
+];
+
+const result = applyUamTransactionApp({ project, operations });
+if (!result.ok) {
+	console.error(result.error.code, result.error.stage, result.error.message);
+}
+```
+
 Repository:
 
 - https://github.com/OpenFairyGUI/OpenFairyGUI

package/dist/index.cjs

@@ -721,7 +721,7 @@ var BinarySearchCompat = class {
 		return this.getCurrent();
 	}
 	getCurrent() {
-		if (this.pot) return Math.trunc(Math.pow(2, this.current));
+		if (this.pot) return Math.trunc(2 ** this.current);
 		if (this.mof) return this.current * 4;
 		return this.current;
 	}
@@ -944,8 +944,8 @@ function swapCompat(items, left, right) {
 function initSizeScheme() {
 	const result = [];
 	for (let w = 5; w <= 13; w += 1) for (let h = 5; h <= 13; h += 1) {
-		const width = Math.pow(2, w);
-		const height = Math.pow(2, h);
+		const width = 2 ** w;
+		const height = 2 ** h;
 		const area = width * height;
 		const aspectRatio = width > height ? width / height : height / width;
 		result.push({
@@ -1915,7 +1915,6 @@ function _readUint32BE(data, offset) {
 }
 /** Collect a Bitmap Font's texture image, packed under the font's ID. */
 async function _collectFontTexture(doc, fontRes, pkg, options) {
-	fontRes.getExtras();
 	const textureId = fontRes.getTextureId?.() ?? "";
 	if (textureId) {
 		const fontId = fontRes.getId();
@@ -3911,8 +3910,42 @@ function _computeDependencies(pkg, pkgMap) {
 	}
 }
 //#endregion
+//#region src/uam-transaction.ts
+function mapTransactionErrorStage(error) {
+	switch (error.code) {
+		case "transaction_unsupported": return "preflight";
+		case "invalid_uam": return "preflight";
+		case "execution_failure": return error.opIndex === void 0 && error.issues !== void 0 ? "postflight" : "execution";
+		case "selector_ambiguity": return error.opIndex === void 0 ? "preflight" : "execution";
+	}
+}
+function applyUamTransactionApp(input) {
+	try {
+		return {
+			ok: true,
+			project: (0, _openfairygui_core.applyUamTransaction)(input.project, input.operations)
+		};
+	} catch (error) {
+		if (error instanceof _openfairygui_core.UamTransactionError) return {
+			ok: false,
+			error: {
+				code: error.code,
+				stage: mapTransactionErrorStage(error),
+				message: error.message,
+				opIndex: error.opIndex,
+				opId: error.opId,
+				opKind: error.opKind,
+				selector: error.selector,
+				issues: error.issues
+			}
+		};
+		throw error;
+	}
+}
+//#endregion
 exports.AUTO_GENERATED_CODE_MARK = AUTO_GENERATED_CODE_MARK;
 exports.ValidationSeverity = ValidationSeverity;
+exports.applyUamTransactionApp = applyUamTransactionApp;
 exports.atlas = atlas;
 exports.createTransform = createTransform;
 exports.inspect = inspect;

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { Document, FileSystem, Package, ProjectSettings, PublishSettings, Transform } from "@openfairygui/core";
+import { Document, FileSystem, Package, ProjectSettings, PublishSettings, Transform, UamProject, UamTransactionErrorCode, UamTransactionOperation, UamTransactionSupportIssue, UamValidationIssue } from "@openfairygui/core";
 
 //#region src/inspect.d.ts
 /**
@@ -456,10 +456,34 @@ declare function resolvePublishOptions(doc: Document, overrides?: ResolvePublish
  */
 declare function publish(options: PublishOptions): Transform;
 //#endregion
+//#region src/uam-transaction.d.ts
+interface ApplyUamTransactionAppInput {
+  project: UamProject;
+  operations: UamTransactionOperation[];
+}
+interface ApplyUamTransactionAppError {
+  code: UamTransactionErrorCode;
+  stage: 'preflight' | 'execution' | 'postflight';
+  message: string;
+  opIndex?: number;
+  opId?: string;
+  opKind?: UamTransactionOperation['kind'];
+  selector?: Record<string, unknown>;
+  issues?: UamValidationIssue[] | UamTransactionSupportIssue[];
+}
+type ApplyUamTransactionAppResult = {
+  ok: true;
+  project: UamProject;
+} | {
+  ok: false;
+  error: ApplyUamTransactionAppError;
+};
+declare function applyUamTransactionApp(input: ApplyUamTransactionAppInput): ApplyUamTransactionAppResult;
+//#endregion
 //#region src/utils.d.ts
 /**
  * Wraps a transform function, assigning it a name for the transform stack.
  */
 declare function createTransform(name: string, fn: Transform): Transform;
 //#endregion
-export { AUTO_GENERATED_CODE_MARK, type AtlasOptions, type CliAtlasSettings, type CliPublishSettings, type ExtrasMap, type HasOptionalFont, type HasOptionalSrc, type HasOptionalUrl, type InspectCategoryReport, type InspectReport, type PruneOptions, type PublishCodeGenerationOptions, type PublishDependency, type PublishFileSystem, type PublishOptions, type RenameOptions, type ResolvePublishOptionsOverrides, type ResolvedPublishAtlasOptions, type ResolvedPublishOptions, type RestoreFileSystem, type RestoreImageCropInput, type RestoreImageCropper, type RestoreImageExtractInput, type RestoreImageExtractor, type RestoreOptions, type RestoreResult, type RootProjectSettings, type ValidateOptions, type ValidationIssue, type ValidationResult, ValidationSeverity, atlas, createTransform, inspect, prune, publish, publishCodeGeneration, rename, resolvePublishOptions, restore, validate };
+export { AUTO_GENERATED_CODE_MARK, type ApplyUamTransactionAppError, type ApplyUamTransactionAppInput, type ApplyUamTransactionAppResult, type AtlasOptions, type CliAtlasSettings, type CliPublishSettings, type ExtrasMap, type HasOptionalFont, type HasOptionalSrc, type HasOptionalUrl, type InspectCategoryReport, type InspectReport, type PruneOptions, type PublishCodeGenerationOptions, type PublishDependency, type PublishFileSystem, type PublishOptions, type RenameOptions, type ResolvePublishOptionsOverrides, type ResolvedPublishAtlasOptions, type ResolvedPublishOptions, type RestoreFileSystem, type RestoreImageCropInput, type RestoreImageCropper, type RestoreImageExtractInput, type RestoreImageExtractor, type RestoreOptions, type RestoreResult, type RootProjectSettings, type ValidateOptions, type ValidationIssue, type ValidationResult, ValidationSeverity, applyUamTransactionApp, atlas, createTransform, inspect, prune, publish, publishCodeGeneration, rename, resolvePublishOptions, restore, validate };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { Document, FileSystem, Package, ProjectSettings, PublishSettings, Transform } from "@openfairygui/core";
+import { Document, FileSystem, Package, ProjectSettings, PublishSettings, Transform, UamProject, UamTransactionErrorCode, UamTransactionOperation, UamTransactionSupportIssue, UamValidationIssue } from "@openfairygui/core";
 
 //#region src/inspect.d.ts
 /**
@@ -456,10 +456,34 @@ declare function resolvePublishOptions(doc: Document, overrides?: ResolvePublish
  */
 declare function publish(options: PublishOptions): Transform;
 //#endregion
+//#region src/uam-transaction.d.ts
+interface ApplyUamTransactionAppInput {
+  project: UamProject;
+  operations: UamTransactionOperation[];
+}
+interface ApplyUamTransactionAppError {
+  code: UamTransactionErrorCode;
+  stage: 'preflight' | 'execution' | 'postflight';
+  message: string;
+  opIndex?: number;
+  opId?: string;
+  opKind?: UamTransactionOperation['kind'];
+  selector?: Record<string, unknown>;
+  issues?: UamValidationIssue[] | UamTransactionSupportIssue[];
+}
+type ApplyUamTransactionAppResult = {
+  ok: true;
+  project: UamProject;
+} | {
+  ok: false;
+  error: ApplyUamTransactionAppError;
+};
+declare function applyUamTransactionApp(input: ApplyUamTransactionAppInput): ApplyUamTransactionAppResult;
+//#endregion
 //#region src/utils.d.ts
 /**
  * Wraps a transform function, assigning it a name for the transform stack.
  */
 declare function createTransform(name: string, fn: Transform): Transform;
 //#endregion
-export { AUTO_GENERATED_CODE_MARK, type AtlasOptions, type CliAtlasSettings, type CliPublishSettings, type ExtrasMap, type HasOptionalFont, type HasOptionalSrc, type HasOptionalUrl, type InspectCategoryReport, type InspectReport, type PruneOptions, type PublishCodeGenerationOptions, type PublishDependency, type PublishFileSystem, type PublishOptions, type RenameOptions, type ResolvePublishOptionsOverrides, type ResolvedPublishAtlasOptions, type ResolvedPublishOptions, type RestoreFileSystem, type RestoreImageCropInput, type RestoreImageCropper, type RestoreImageExtractInput, type RestoreImageExtractor, type RestoreOptions, type RestoreResult, type RootProjectSettings, type ValidateOptions, type ValidationIssue, type ValidationResult, ValidationSeverity, atlas, createTransform, inspect, prune, publish, publishCodeGeneration, rename, resolvePublishOptions, restore, validate };
+export { AUTO_GENERATED_CODE_MARK, type ApplyUamTransactionAppError, type ApplyUamTransactionAppInput, type ApplyUamTransactionAppResult, type AtlasOptions, type CliAtlasSettings, type CliPublishSettings, type ExtrasMap, type HasOptionalFont, type HasOptionalSrc, type HasOptionalUrl, type InspectCategoryReport, type InspectReport, type PruneOptions, type PublishCodeGenerationOptions, type PublishDependency, type PublishFileSystem, type PublishOptions, type RenameOptions, type ResolvePublishOptionsOverrides, type ResolvedPublishAtlasOptions, type ResolvedPublishOptions, type RestoreFileSystem, type RestoreImageCropInput, type RestoreImageCropper, type RestoreImageExtractInput, type RestoreImageExtractor, type RestoreOptions, type RestoreResult, type RootProjectSettings, type ValidateOptions, type ValidationIssue, type ValidationResult, ValidationSeverity, applyUamTransactionApp, atlas, createTransform, inspect, prune, publish, publishCodeGeneration, rename, resolvePublishOptions, restore, validate };

package/dist/index.js

@@ -1,4 +1,4 @@
-import { BinaryReader, BinaryWriter, GearType, ProjectType, ProjectWriter, TransitionActionType, generateId } from "@openfairygui/core";
+import { BinaryReader, BinaryWriter, GearType, ProjectType, ProjectWriter, TransitionActionType, UamTransactionError, applyUamTransaction, generateId } from "@openfairygui/core";
 //#region src/inspect.ts
 function mapResource(resource) {
 	return {
@@ -720,7 +720,7 @@ var BinarySearchCompat = class {
 		return this.getCurrent();
 	}
 	getCurrent() {
-		if (this.pot) return Math.trunc(Math.pow(2, this.current));
+		if (this.pot) return Math.trunc(2 ** this.current);
 		if (this.mof) return this.current * 4;
 		return this.current;
 	}
@@ -943,8 +943,8 @@ function swapCompat(items, left, right) {
 function initSizeScheme() {
 	const result = [];
 	for (let w = 5; w <= 13; w += 1) for (let h = 5; h <= 13; h += 1) {
-		const width = Math.pow(2, w);
-		const height = Math.pow(2, h);
+		const width = 2 ** w;
+		const height = 2 ** h;
 		const area = width * height;
 		const aspectRatio = width > height ? width / height : height / width;
 		result.push({
@@ -1914,7 +1914,6 @@ function _readUint32BE(data, offset) {
 }
 /** Collect a Bitmap Font's texture image, packed under the font's ID. */
 async function _collectFontTexture(doc, fontRes, pkg, options) {
-	fontRes.getExtras();
 	const textureId = fontRes.getTextureId?.() ?? "";
 	if (textureId) {
 		const fontId = fontRes.getId();
@@ -3910,4 +3909,37 @@ function _computeDependencies(pkg, pkgMap) {
 	}
 }
 //#endregion
-export { AUTO_GENERATED_CODE_MARK, ValidationSeverity, atlas, createTransform, inspect, prune, publish, publishCodeGeneration, rename, resolvePublishOptions, restore, validate };
+//#region src/uam-transaction.ts
+function mapTransactionErrorStage(error) {
+	switch (error.code) {
+		case "transaction_unsupported": return "preflight";
+		case "invalid_uam": return "preflight";
+		case "execution_failure": return error.opIndex === void 0 && error.issues !== void 0 ? "postflight" : "execution";
+		case "selector_ambiguity": return error.opIndex === void 0 ? "preflight" : "execution";
+	}
+}
+function applyUamTransactionApp(input) {
+	try {
+		return {
+			ok: true,
+			project: applyUamTransaction(input.project, input.operations)
+		};
+	} catch (error) {
+		if (error instanceof UamTransactionError) return {
+			ok: false,
+			error: {
+				code: error.code,
+				stage: mapTransactionErrorStage(error),
+				message: error.message,
+				opIndex: error.opIndex,
+				opId: error.opId,
+				opKind: error.opKind,
+				selector: error.selector,
+				issues: error.issues
+			}
+		};
+		throw error;
+	}
+}
+//#endregion
+export { AUTO_GENERATED_CODE_MARK, ValidationSeverity, applyUamTransactionApp, atlas, createTransform, inspect, prune, publish, publishCodeGeneration, rename, resolvePublishOptions, restore, validate };

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@openfairygui/functions",
-	"version": "0.1.1",
+	"version": "0.2.0-alpha.1",
 	"description": "FairyGUI Headless Authoring SDK — composable transform functions.",
 	"author": "OpenFairyGUI Contributors",
 	"license": "MIT",

package/src/atlas.ts

@@ -131,7 +131,6 @@ interface TrimInfo {
 type PackageResource = ReturnType<Package['listResources']>[number];
 type PackableResource = ImageResource | MovieClipResource | FontResource;
 type PackInputResource = ImageResource | MovieClipResource;
-type ParsedFnt = ReturnType<typeof _parseFnt>;
 
 function getPublishedItemId(resource: { getId(): string; getExtras(): ExtrasMap | undefined }): string {
 	return ((resource.getExtras() as ImageResourceExtras | undefined) ?? {})._publishedId ?? resource.getId();
@@ -253,60 +252,6 @@ function resolveFontFileName(fontName: string): string {
 	return /\.fnt$/i.test(fontName) ? fontName : `${fontName}.fnt`;
 }
 
-function addLocalResourceByUiUrl(
-	target: PackageResource[],
-	added: Set<string>,
-	resourceMap: Map<string, PackageResource>,
-	pkgId: string,
-	value: string | null | undefined,
-): void {
-	if (!value || typeof value !== 'string' || !value.startsWith('ui://')) return;
-	const normalized = value.slice(5).split(',')[0] ?? '';
-	if (!normalized) return;
-	let resourceId = '';
-	const slashIndex = normalized.indexOf('/');
-	if (slashIndex >= 0) {
-		const packageToken = normalized.slice(0, slashIndex);
-		if (packageToken !== pkgId) return;
-		resourceId = normalized.slice(slashIndex + 1);
-	} else if (normalized.length > 8) {
-		const packageToken = normalized.slice(0, 8);
-		if (packageToken !== pkgId) return;
-		resourceId = normalized.slice(8);
-	}
-	if (!resourceId) return;
-	const resource = resourceMap.get(resourceId);
-	if (!resource || added.has(resourceId)) return;
-	added.add(resourceId);
-	target.push(resource);
-}
-
-function addLocalResourcesByText(
-	target: PackageResource[],
-	added: Set<string>,
-	resourceMap: Map<string, PackageResource>,
-	pkgId: string,
-	value: string | null | undefined,
-): void {
-	if (!value || typeof value !== 'string') return;
-	for (const match of value.matchAll(/ui:\/\/[0-9a-z]{8}[0-9a-z]+/gi)) {
-		addLocalResourceByUiUrl(target, added, resourceMap, pkgId, match[0]);
-	}
-}
-
-function addResourceById(
-	target: PackageResource[],
-	added: Set<string>,
-	resourceMap: Map<string, PackageResource>,
-	resourceId: string | null | undefined,
-): void {
-	if (!resourceId) return;
-	const resource = resourceMap.get(resourceId);
-	if (!resource || added.has(resourceId)) return;
-	added.add(resourceId);
-	target.push(resource);
-}
-
 async function resolveEditorCompatibleResourceOrder(
 	pkg: Package,
 	allResources: PackageResource[],
@@ -1473,7 +1418,6 @@ async function _collectFontTexture(
 	pkg: Package,
 	options: AtlasOptions,
 ): Promise<void> {
-	const extras = fontRes.getExtras() as FontResourceExtras;
 	const textureId = fontRes.getTextureId?.() ?? '';
 
 	if (textureId) {

package/src/index.ts

@@ -22,6 +22,12 @@ export {
 	type ResolvedPublishOptions,
 	type ResolvePublishOptionsOverrides,
 } from './publish.js';
+export {
+	applyUamTransactionApp,
+	type ApplyUamTransactionAppError,
+	type ApplyUamTransactionAppInput,
+	type ApplyUamTransactionAppResult,
+} from './uam-transaction.js';
 export { createTransform } from './utils.js';
 export type {
 	CliAtlasSettings,

package/src/max-rects-packer-compat.ts

@@ -78,7 +78,7 @@ class BinarySearchCompat {
 	}
 
 	private getCurrent(): number {
-		if (this.pot) return Math.trunc(Math.pow(2, this.current));
+		if (this.pot) return Math.trunc(2 ** this.current);
 		if (this.mof) return this.current * 4;
 		return this.current;
 	}
@@ -323,8 +323,8 @@ function initSizeScheme(): Array<{ width: number; height: number; area: number;
 	const result = [];
 	for (let w = 5; w <= 13; w += 1) {
 		for (let h = 5; h <= 13; h += 1) {
-			const width = Math.pow(2, w);
-			const height = Math.pow(2, h);
+			const width = 2 ** w;
+			const height = 2 ** h;
 			const area = width * height;
 			const aspectRatio = width > height ? width / height : height / width;
 			result.push({ width, height, area, aspectRatio, len: Math.max(width, height) });

package/src/uam-transaction.ts

@@ -0,0 +1,68 @@
+import {
+	applyUamTransaction,
+	type UamProject,
+	UamTransactionError,
+	type UamTransactionErrorCode,
+	type UamTransactionOperation,
+	type UamTransactionSupportIssue,
+	type UamValidationIssue,
+} from '@openfairygui/core';
+
+export interface ApplyUamTransactionAppInput {
+	project: UamProject;
+	operations: UamTransactionOperation[];
+}
+
+export interface ApplyUamTransactionAppError {
+	code: UamTransactionErrorCode;
+	stage: 'preflight' | 'execution' | 'postflight';
+	message: string;
+	opIndex?: number;
+	opId?: string;
+	opKind?: UamTransactionOperation['kind'];
+	selector?: Record<string, unknown>;
+	issues?: UamValidationIssue[] | UamTransactionSupportIssue[];
+}
+
+export type ApplyUamTransactionAppResult =
+	| { ok: true; project: UamProject }
+	| { ok: false; error: ApplyUamTransactionAppError };
+
+function mapTransactionErrorStage(error: UamTransactionError): ApplyUamTransactionAppError['stage'] {
+	switch (error.code) {
+		case 'transaction_unsupported':
+			return 'preflight';
+		case 'invalid_uam':
+			return 'preflight';
+		case 'execution_failure':
+			return error.opIndex === undefined && error.issues !== undefined ? 'postflight' : 'execution';
+		case 'selector_ambiguity':
+			return error.opIndex === undefined ? 'preflight' : 'execution';
+	}
+}
+
+export function applyUamTransactionApp(input: ApplyUamTransactionAppInput): ApplyUamTransactionAppResult {
+	try {
+		return {
+			ok: true,
+			project: applyUamTransaction(input.project, input.operations),
+		};
+	} catch (error) {
+		if (error instanceof UamTransactionError) {
+			return {
+				ok: false,
+				error: {
+					code: error.code,
+					stage: mapTransactionErrorStage(error),
+					message: error.message,
+					opIndex: error.opIndex,
+					opId: error.opId,
+					opKind: error.opKind,
+					selector: error.selector,
+					issues: error.issues,
+				},
+			};
+		}
+		throw error;
+	}
+}