broapp 0.2.0 → 0.4.0

package/src/shared/errors.ts

@@ -80,6 +80,60 @@ export class PublicError extends Error {
   }
 }
 
+/**
+ * True when `error` is a {@link PublicError}, including one from another copy
+ * of this module.
+ *
+ * `instanceof` is not enough, and the reason is architectural rather than
+ * pedantic. An Autoapp release bundles its own copy of `broapp`, while the
+ * child runtime that supervises it has the copy compiled into the launcher —
+ * so a `PublicError` thrown by the gate in one and caught by `runOperation` in
+ * the other is a different class object with the same shape. Reducing it to
+ * "internal error" would silently turn every deliberate refusal, the preview
+ * policy's included, into a mystery.
+ *
+ * The check is deliberately narrow: the name, and a `code` from the known set.
+ * Nothing an untrusted value could set by accident.
+ */
+export function isPublicError(error: unknown): error is PublicError {
+  // No `instanceof PublicError` fast path. It would be true for one of the two
+  // copies and false for the other, and a check whose answer depends on which
+  // bundle asked is the bug this function exists to fix — including in the
+  // reader's mind, the next time somebody copies this shape.
+  if (!(error instanceof Error) || error.name !== 'PublicError') return false;
+  const code: unknown = (error as { code?: unknown }).code;
+  return typeof code === 'string' && (PUBLIC_CODES as readonly string[]).includes(code);
+}
+
+/**
+ * True when `error` is a {@link BroappError}, including one from another copy
+ * of this module.
+ *
+ * Same reason as {@link isPublicError}. `fromTransportError` is shared code:
+ * the browser calls it inside one bundle, and the Autoapp child runtime calls
+ * it on an error that came out of a release's own bundle.
+ */
+function isBroappError(error: unknown): error is BroappError {
+  if (!(error instanceof Error) || error.name !== 'BroappError') return false;
+  const code: unknown = (error as { code?: unknown }).code;
+  return typeof code === 'string' && (PUBLIC_CODES as readonly string[]).includes(code);
+}
+
+/**
+ * True when `error` is Brobridge's cancellation, from any copy of Brobridge.
+ *
+ * A release bundles its own, so the class identity is not shared. `ErrorCode`
+ * is a set of string constants rather than a symbol, which is what makes the
+ * value comparison meaningful across copies.
+ */
+function isCancelled(error: unknown): boolean {
+  return (
+    error instanceof Error &&
+    error.name === 'BridgeError' &&
+    (error as { code?: unknown }).code === ErrorCode.CANCELLED
+  );
+}
+
 /** The message every unhandled host failure becomes, on both sides. */
 export const INTERNAL_ERROR_MESSAGE = 'The application could not complete that operation.';
 
@@ -105,7 +159,7 @@ export class BroappError extends Error {
  * for a user to read.
  */
 export function fromTransportError(error: unknown): BroappError {
-  if (error instanceof BroappError) return error;
+  if (isBroappError(error)) return error;
   const message = error instanceof Error ? error.message : '';
   if (message.startsWith(MARKER)) {
     const space = message.indexOf(' ');
@@ -118,7 +172,7 @@ export function fromTransportError(error: unknown): BroappError {
       );
     }
   }
-  if (error instanceof BridgeError && error.code === ErrorCode.CANCELLED) {
+  if (isCancelled(error)) {
     return new BroappError('rejected', 'The operation was cancelled.', error);
   }
   return new BroappError('internal', INTERNAL_ERROR_MESSAGE, error);

package/src/shared/index.ts

@@ -8,6 +8,7 @@
 export {
   assertNoReservedRoutes,
   defineContract,
+  effectOf,
   mergeContracts,
   RESERVED_GROUPS,
   splitRoute,
@@ -16,6 +17,7 @@ export type {
   AnyContract,
   Contract,
   ContractShape,
+  Effect,
   ShapeOf,
   OperationInput,
   OperationName,
@@ -27,7 +29,7 @@ export type {
   StreamSpec,
 } from './contract.ts';
 
-export { s, ValidationError } from './schema.ts';
+export { isValidationError, s, ValidationError } from './schema.ts';
 export type { Infer, InferObject, Issue, JsonSchema, Result, Schema } from './schema.ts';
 
 export {
@@ -35,8 +37,11 @@ export {
   INTERNAL_ERROR_MESSAGE,
   PublicError,
   fromTransportError,
+  isPublicError,
   publicError,
 } from './errors.ts';
 export type { PublicErrorCode } from './errors.ts';
 
 export { encodeEvent, MAX_EVENT_BYTES, NdjsonDecoder } from './ndjson.ts';
+
+export { countdown, isUrgent, remainingMs, URGENT_MS } from './countdown.ts';

package/src/shared/schema.ts

@@ -35,6 +35,22 @@ export class ValidationError extends Error {
   }
 }
 
+/**
+ * True when `error` is a {@link ValidationError}, including one from another
+ * copy of this module.
+ *
+ * `instanceof` is not enough for the same reason it is not enough for
+ * `PublicError`: an Autoapp release bundles its own copy of `broapp`, so a
+ * schema built in one bundle and parsed by code in another throws a different
+ * class object with the same shape. Reducing that to "invalid input" with no
+ * message would tell a caller nothing about what was actually wrong.
+ */
+export function isValidationError(error: unknown): error is ValidationError {
+  return (
+    error instanceof Error && error.name === 'ValidationError' && Array.isArray((error as { issues?: unknown }).issues)
+  );
+}
+
 function formatPath(path: IssuePath): string {
   let out = '';
   for (const segment of path) {