@spine-event-engine/proto-tools 2.0.0-snapshot.14 → 2.0.0-snapshot.16

package/README.md

@@ -82,6 +82,11 @@ source imports the Server handler-registry contract as a type from
 runtime dependency. Run both after the related model or handler changes.
 The handler analyzer records `@Throws(...)` declarations as rejection outcomes;
 the generated rejection companion supplies the schema used by that metadata.
+Handler results can use native message unions, flat arrays, fixed tuples with
+optional entries, and one outer `Promise`. Concrete local/imported aliases are
+resolved too. The [handler return guide](https://github.com/SpineEventEngine/spine-ts/blob/master/docs/USER_GUIDE.md#choose-what-a-handler-returns)
+shows the allowed forms and the rules for each decorator. Regenerate handlers
+after changing a return declaration so every possible result schema is registered.
 
 The public CLI is `spine-proto`. Programmatic config and manifest readers are
 for build tooling that needs the same validated package contracts; application

package/REFERENCE.md

@@ -76,6 +76,15 @@ sufficient because `TypeRegistry.from()` follows declared dependencies.
 `handlers` must run after a decorated handler or its generated command, event,
 or state types change. Compile the generated registry with the application.
 
+Explicit handler return annotations may resolve to one generated message, a
+union, a flat array, or a fixed tuple (including readonly, named, optional, and
+union-valued entries), optionally wrapped in one built-in `Promise`. Local and
+imported aliases must resolve to concrete generated schemas. The analyzer records
+all possible schemas in that handler's `outcomes.returned`; it does not serialize
+tuple positions or union branches. Handler-specific result rules and unsupported
+shapes are documented in the
+[server reference](https://github.com/SpineEventEngine/spine-ts/blob/master/packages/server/REFERENCE.md#handler-return-types).
+
 ## Safety and atomicity
 
 All package-relative paths must remain inside the package and may not use unsafe

package/dist/src/generation/build-time-handler-analyzer.d.ts

@@ -156,7 +156,7 @@ export interface BuildWhereOptions {
 /**
  * Stable diagnostic codes emitted by build-time handler analysis.
  */
-export type BuildHandlerDiagnosticCode = "APPLY_DECORATOR" | "FRAMEWORK_ENVELOPE_RETURN" | "INVALID_EMITTED_SCHEMA" | "INVALID_HANDLER_NAME" | "INVALID_HANDLER_CONTEXT" | "INVALID_HANDLER_VISIBILITY" | "INVALID_PARAMETER_COUNT" | "INVALID_SIGNAL_TYPE" | "INVALID_EXTERNAL_ORIGIN" | "EXTERNAL_COMMAND_RECEIVER" | "INVALID_SUBSCRIBE_RETURN" | "INVALID_THROWS" | "INVALID_WHERE" | "MISSING_EMITTED_SCHEMAS" | "MISSING_ENTITY_STATE_SCHEMA" | "MISSING_RETURN_TYPE" | "MISSING_SIGNAL_TYPE" | "NON_EXPORTED_RECEIVER_CLASS" | "SCHEMA_BEARING_DECORATOR" | "TYPESCRIPT_SYNTAX_ERROR" | "UNSUPPORTED_ASSIGN_HANDLER" | "UNSUPPORTED_COMMAND_HANDLER" | "UNSUPPORTED_RETURN_TYPE";
+export type BuildHandlerDiagnosticCode = "FRAMEWORK_ENVELOPE_RETURN" | "INVALID_EMITTED_SCHEMA" | "INVALID_HANDLER_NAME" | "INVALID_HANDLER_CONTEXT" | "INVALID_HANDLER_VISIBILITY" | "INVALID_PARAMETER_COUNT" | "INVALID_SIGNAL_TYPE" | "INVALID_EXTERNAL_ORIGIN" | "EXTERNAL_COMMAND_RECEIVER" | "INVALID_SUBSCRIBE_RETURN" | "INVALID_THROWS" | "INVALID_WHERE" | "MISSING_EMITTED_SCHEMAS" | "MISSING_ENTITY_STATE_SCHEMA" | "MISSING_RETURN_TYPE" | "MISSING_SIGNAL_TYPE" | "NON_EXPORTED_RECEIVER_CLASS" | "SCHEMA_BEARING_DECORATOR" | "TYPESCRIPT_SYNTAX_ERROR" | "UNSUPPORTED_ASSIGN_HANDLER" | "UNSUPPORTED_COMMAND_HANDLER" | "UNSUPPORTED_RETURN_TYPE";
 /**
  * One build-time analyzer diagnostic.
  */

package/dist/src/generation/build-time-handler-analyzer.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"build-time-handler-analyzer.d.ts","sourceRoot":"","sources":["../../../src/generation/build-time-handler-analyzer.ts"],"names":[],"mappings":"AAqBA,OAAO,EAAE,MAAM,YAAY,CAAC;AAE5B,KAAK,oBAAoB,GACrB,oBAAoB,GACpB,sBAAsB,GACtB,kBAAkB,GAClB,oBAAoB,GACpB,oBAAoB,GACpB,gBAAgB,CAAC;AACrB,KAAK,8BAA8B,GAAG,CAAC,GAAG,CAAC,CAAC;AAE5C;;GAEG;AACH,MAAM,WAAW,oBAAoB;IAGnC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,SAAS,qBAAqB,EAAE,CAAC;IAErD;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,SAAS,sBAAsB,EAAE,CAAC;CACzD;AAED;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAGlC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC;IAEhC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,WAAW,EAAE,eAAe,CAAC;IAEtC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAClD;AAED;;GAEG;AACH,MAAM,WAAW,uBAAuB;IAGtC;;OAEG;IACH,QAAQ,CAAC,YAAY,EAAE,YAAY,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAE3B;;OAEG;IACH,QAAQ,CAAC,aAAa,CAAC,EAAE,OAAO,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,kBAAkB,EAAE,CAAC;CAClD;AAED;;GAEG;AACH,MAAM,MAAM,qBAAqB,GAAG,mBAAmB,GAAG,uBAAuB,CAAC;AAElF;;GAEG;AACH,MAAM,WAAW,eAAe;IAG9B;;OAEG;IACH,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;CAC7B;AAED;;GAEG;AACH,MAAM,WAAW,kBAAkB;IAGjC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,oBAAoB,CAAC;IAEpC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,KAAK,EAAE,iBAAiB,CAAC;IAElC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,oBAAoB,CAAC;IAExC;;OAEG;IACH,QAAQ,CAAC,cAAc,EAAE,8BAA8B,CAAC;CACzD;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAGhC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,eAAe,CAAC;IAEjC;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,UAAU,GAAG,UAAU,CAAC;IAEzC;;OAEG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,iBAAiB,CAAC;CACpC;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IAGnC;;OAEG;IACH,QAAQ,CAAC,QAAQ,EAAE,SAAS,eAAe,EAAE,CAAC;IAE9C;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,SAAS,eAAe,EAAE,CAAC;CAC7C;AAED;;GAEG;AACH,MAAM,WAAW,iBAAiB;IAGhC;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB;AAYD;;GAEG;AACH,MAAM,MAAM,0BAA0B,GAClC,iBAAiB,GACjB,2BAA2B,GAC3B,wBAAwB,GACxB,sBAAsB,GACtB,yBAAyB,GACzB,4BAA4B,GAC5B,yBAAyB,GACzB,qBAAqB,GACrB,yBAAyB,GACzB,2BAA2B,GAC3B,0BAA0B,GAC1B,gBAAgB,GAChB,eAAe,GACf,yBAAyB,GACzB,6BAA6B,GAC7B,qBAAqB,GACrB,qBAAqB,GACrB,6BAA6B,GAC7B,0BAA0B,GAC1B,yBAAyB,GACzB,4BAA4B,GAC5B,6BAA6B,GAC7B,yBAAyB,CAAC;AAE9B;;GAEG;AACH,MAAM,WAAW,sBAAsB;IAGrC;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,0BAA0B,CAAC;IAE1C;;OAEG;IACH,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IAEtB;;OAEG;IACH,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IAExB;;OAEG;IACH,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IAEzB;;OAEG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAE5B;;OAEG;IACH,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;GAEG;AACH,MAAM,WAAW,oBAAoB;IAGnC;;;;;;OAMG;IACH,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,OAAO,EAAE,WAAW,CAAC,EAAE,SAAS,EAAE,CAAC,UAAU,EAAE,GAAG,oBAAoB,CAAC;CAC5F;AAED;;GAEG;AACH,eAAO,MAAM,oBAAoB,EAAE,oBAyCjC,CAAC;AAouEH;;GAEG;AACH,eAAO,MAAM,eAAe,EAAE,QAAQ,CAAC;IAAE,OAAO,CAAC,UAAU,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAAA;CAAE,CAkBtF,CAAC"}
+{"version":3,"file":"build-time-handler-analyzer.d.ts","sourceRoot":"","sources":["../../../src/generation/build-time-handler-analyzer.ts"],"names":[],"mappings":"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"}