effect 4.0.0-beta.4 → 4.0.0-beta.41

package/src/unstable/cli/internal/parser.ts

@@ -20,19 +20,17 @@
  *
  * Key Behaviors
  * -------------
- * - Parent flags may appear before OR after the subcommand name (npm-style)
+ * - Inherited parent flags may appear before OR after the subcommand name (npm-style)
  * - Only the first Value token can open a subcommand
  * - Errors accumulate rather than throwing exceptions
  */
 import * as Effect from "../../../Effect.ts"
-import type { LogLevel } from "../../../LogLevel.ts"
 import * as Option from "../../../Option.ts"
 import * as CliError from "../CliError.ts"
 import type { Command, ParsedTokens } from "../Command.ts"
 import * as Param from "../Param.ts"
 import * as Primitive from "../Primitive.ts"
 import { suggest } from "./auto-suggest.ts"
-import { completionsFlag, helpFlag, logLevelFlag, versionFlag } from "./builtInFlags.ts"
 import { toImpl } from "./command.ts"
 import type { LexResult, Token } from "./lexer.ts"
 
@@ -42,38 +40,9 @@ import type { LexResult, Token } from "./lexer.ts"
 
 /** @internal */
 export const getCommandPath = (parsedInput: ParsedTokens): ReadonlyArray<string> =>
-  parsedInput.subcommand
-    ? [parsedInput.subcommand.name, ...getCommandPath(parsedInput.subcommand.parsedInput)]
-    : []
-
-/** @internal */
-export const extractBuiltInOptions = (
-  tokens: ReadonlyArray<Token>
-): Effect.Effect<
-  {
-    help: boolean
-    logLevel: LogLevel | undefined
-    version: boolean
-    completions: "bash" | "zsh" | "fish" | undefined
-    remainder: ReadonlyArray<Token>
-  },
-  CliError.CliError,
-  Param.Environment
-> =>
-  Effect.gen(function*() {
-    const { flagMap, remainder } = consumeKnownFlags(tokens, builtInFlagRegistry)
-    const emptyArgs: Param.ParsedArgs = { flags: flagMap, arguments: [] }
-    const [, help] = yield* helpFlag.parse(emptyArgs)
-    const [, logLevel] = yield* logLevelFlag.parse(emptyArgs)
-    const [, version] = yield* versionFlag.parse(emptyArgs)
-    const [, completions] = yield* completionsFlag.parse(emptyArgs)
-    return {
-      help,
-      logLevel: Option.getOrUndefined(logLevel),
-      version,
-      completions: Option.getOrUndefined(completions),
-      remainder
-    }
+  Option.match(parsedInput.subcommand, {
+    onNone: () => [],
+    onSome: (subcommand) => [subcommand.name, ...getCommandPath(subcommand.parsedInput)]
   })
 
 /** @internal */
@@ -91,10 +60,17 @@ export const parseArgs = (
     const flagParams = singles.filter(Param.isFlagParam)
     const flagRegistry = createFlagRegistry(flagParams)
 
+    const inheritedSingles = commandImpl.contextConfig.flags.flatMap(Param.extractSingleParams)
+    const inheritedFlagParams = inheritedSingles.filter(Param.isFlagParam)
+    const inheritedFlagRegistry = createFlagRegistry(inheritedFlagParams)
+    const inheritedNames = new Set(inheritedFlagParams.map((param) => param.name))
+
     const context: CommandContext = {
       command,
       commandPath: newCommandPath,
-      flagRegistry
+      flagRegistry,
+      inheritedFlagRegistry,
+      localFlagNames: flagParams.filter((param) => !inheritedNames.has(param.name)).map((param) => param.name)
     }
 
     const result = scanCommandLevel(tokens, context)
@@ -103,6 +79,7 @@ export const parseArgs = (
       return {
         flags: result.flags,
         arguments: [...result.arguments, ...afterEndOfOptions],
+        subcommand: Option.none(),
         ...(result.errors.length > 0 && { errors: result.errors })
       }
     }
@@ -118,7 +95,7 @@ export const parseArgs = (
     return {
       flags: result.flags,
       arguments: afterEndOfOptions,
-      subcommand: { name: result.sub.name, parsedInput: subParsed },
+      subcommand: Option.some({ name: result.sub.name, parsedInput: subParsed }),
       ...(allErrors.length > 0 && { errors: allErrors })
     }
   })
@@ -166,6 +143,8 @@ type CommandContext = {
   readonly command: Command.Any
   readonly commandPath: ReadonlyArray<string>
   readonly flagRegistry: FlagRegistry
+  readonly inheritedFlagRegistry: FlagRegistry
+  readonly localFlagNames: ReadonlyArray<string>
 }
 
 /**
@@ -209,7 +188,7 @@ type LeafResult = {
 type SubcommandResult = {
   readonly _tag: "Sub"
   readonly flags: Readonly<FlagMap>
-  readonly sub: Command<string, unknown, unknown, unknown>
+  readonly sub: Command<string, unknown, unknown, unknown, unknown>
   readonly childTokens: ReadonlyArray<Token>
   readonly errors: ReadonlyArray<CliError.CliError>
 }
@@ -249,8 +228,9 @@ const makeCursor = (tokens: ReadonlyArray<Token>): TokenCursor => {
 /**
  * Creates a registry for O(1) flag lookup by name or alias.
  * @throws Error if duplicate names or aliases are detected (developer error)
+ * @internal
  */
-const createFlagRegistry = (params: ReadonlyArray<FlagParam>): FlagRegistry => {
+export const createFlagRegistry = (params: ReadonlyArray<FlagParam>): FlagRegistry => {
   const index = new Map<string, FlagParam>()
 
   for (const param of params) {
@@ -273,15 +253,38 @@ const createFlagRegistry = (params: ReadonlyArray<FlagParam>): FlagRegistry => {
 }
 
 const buildSubcommandIndex = (
-  subcommands: ReadonlyArray<Command<string, unknown, unknown, unknown>>
-): Map<string, Command<string, unknown, unknown, unknown>> => new Map(subcommands.map((sub) => [sub.name, sub]))
+  subcommands: Command.Any["subcommands"]
+): Map<string, Command<string, unknown, unknown, unknown, unknown>> => {
+  const index = new Map<string, Command<string, unknown, unknown, unknown, unknown>>()
+  const setKey = (key: string, command: Command<string, unknown, unknown, unknown, unknown>) => {
+    const existing = index.get(key)
+    if (existing && existing !== command) {
+      throw new Error(
+        `Duplicate subcommand name/alias "${key}" in command definition (conflicts with "${existing.name}")`
+      )
+    }
+    index.set(key, command)
+  }
+
+  for (const group of subcommands) {
+    for (const subcommand of group.commands) {
+      setKey(subcommand.name, subcommand)
+      if (subcommand.alias && subcommand.alias !== subcommand.name) {
+        setKey(subcommand.alias, subcommand)
+      }
+    }
+  }
+  return index
+}
 
 /* ========================================================================== */
 /* Flag Accumulator                                                           */
 /* ========================================================================== */
 
-/** Creates an empty flag map with all known flag names initialized to []. */
-const createEmptyFlagMap = (params: ReadonlyArray<FlagParam>): FlagMap =>
+/** Creates an empty flag map with all known flag names initialized to [].
+ * @internal
+ */
+export const createEmptyFlagMap = (params: ReadonlyArray<FlagParam>): FlagMap =>
   Object.fromEntries(params.map((p) => [p.name, []]))
 
 /**
@@ -370,9 +373,10 @@ const consumeFlagValue = (
 /**
  * Consumes known flags from a token stream.
  * Unrecognized tokens are passed through to remainder.
- * Used for both built-in extraction and npm-style parent flag collection.
+ * Used for both global flag extraction and npm-style parent flag collection.
+ * @internal
  */
-const consumeKnownFlags = (
+export const consumeKnownFlags = (
   tokens: ReadonlyArray<Token>,
   registry: FlagRegistry
 ): { flagMap: FlagMap; remainder: ReadonlyArray<Token> } => {
@@ -401,19 +405,6 @@ const consumeKnownFlags = (
   return { flagMap, remainder }
 }
 
-/* ========================================================================== */
-/* Built-in Flags                                                             */
-/* ========================================================================== */
-
-const builtInFlagParams: ReadonlyArray<FlagParam> = [
-  ...Param.extractSingleParams(logLevelFlag),
-  ...Param.extractSingleParams(helpFlag),
-  ...Param.extractSingleParams(versionFlag),
-  ...Param.extractSingleParams(completionsFlag)
-]
-
-const builtInFlagRegistry = createFlagRegistry(builtInFlagParams)
-
 /* ========================================================================== */
 /* Error Creation                                                             */
 /* ========================================================================== */
@@ -469,7 +460,7 @@ const toLeafResult = (state: ParseState): LeafResult => ({
  * Determines how to handle the first value token.
  *
  * If it matches a known subcommand:
- * - Collect any parent flags from remaining tokens (npm-style)
+ * - Collect inherited parent flags from remaining tokens (npm-style)
  * - Return SubcommandResult with child tokens
  *
  * Otherwise:
@@ -482,13 +473,30 @@ const resolveFirstValue = (
   context: CommandContext,
   state: ParseState
 ): FirstValueResult => {
-  const { command, commandPath, flagRegistry } = context
+  const { command, commandPath, inheritedFlagRegistry, localFlagNames } = context
   const subIndex = buildSubcommandIndex(command.subcommands)
   const sub = subIndex.get(value)
 
   if (sub) {
-    // npm-style: parent flags can appear after subcommand name
-    const tail = consumeKnownFlags(cursor.rest(), flagRegistry)
+    const selectedPath = [...commandPath, sub.name]
+
+    // Local flags are not inherited by subcommands.
+    const parentFlags = state.flags.snapshot()
+    for (const localFlagName of localFlagNames) {
+      const values = parentFlags[localFlagName]
+      if (values !== undefined && values.length > 0) {
+        state.errors.push(
+          new CliError.UnrecognizedOption({
+            option: `--${localFlagName}`,
+            suggestions: [],
+            command: selectedPath
+          })
+        )
+      }
+    }
+
+    // npm-style: inherited parent flags can appear after subcommand name
+    const tail = consumeKnownFlags(cursor.rest(), inheritedFlagRegistry)
     state.flags.merge(tail.flagMap)
 
     return {
@@ -506,7 +514,7 @@ const resolveFirstValue = (
   // Not a subcommand. Check if this looks like a typo.
   const expectsArgs = toImpl(command).config.arguments.length > 0
   if (!expectsArgs && subIndex.size > 0) {
-    const suggestions = suggest(value, command.subcommands.map((s) => s.name))
+    const suggestions = suggest(value, Array.from(subIndex.keys()))
     state.errors.push(
       new CliError.UnknownSubcommand({
         subcommand: value,

package/src/unstable/cluster/ClusterCron.ts

@@ -51,7 +51,7 @@ export const make = <E, R>(options: {
    *
    * Defaults to "1 day".
    */
-  readonly skipIfOlderThan?: Duration.DurationInput | undefined
+  readonly skipIfOlderThan?: Duration.Input | undefined
 }): Layer.Layer<never, never, Sharding | Exclude<R, Scope>> => {
   const CronEntity = Entity.make(`ClusterCron/${options.name}`, [
     Rpc.make("run", {
@@ -76,7 +76,7 @@ export const make = <E, R>(options: {
   )
 
   const skipIfOlderThan = Option.fromUndefinedOr(options.skipIfOlderThan).pipe(
-    Option.map(Duration.fromDurationInputUnsafe),
+    Option.map(Duration.fromInputUnsafe),
     Option.getOrElse(() => Duration.days(1))
   )
 

package/src/unstable/cluster/ClusterSchema.ts

@@ -1,9 +1,11 @@
 /**
  * @since 4.0.0
  */
-import { constFalse, constTrue } from "../../Function.ts"
+import { constFalse, constTrue, identity } from "../../Function.ts"
 import * as ServiceMap from "../../ServiceMap.ts"
+import type * as Rpc from "../rpc/Rpc.ts"
 import type { EntityId } from "./EntityId.ts"
+import type { Request } from "./Envelope.ts"
 
 /**
  * @since 4.0.0
@@ -13,6 +15,18 @@ export const Persisted = ServiceMap.Reference<boolean>("effect/cluster/ClusterSc
   defaultValue: constFalse
 })
 
+/**
+ * Whether to wrap the request with a storage transaction, so sql queries are
+ * committed atomically.
+ *
+ * @since 4.0.0
+ * @category Annotations
+ */
+export const WithTransaction = ServiceMap.Reference<boolean>(
+  "effect/cluster/ClusterSchema/WithTransaction",
+  { defaultValue: constFalse }
+)
+
 /**
  * @since 4.0.0
  * @category Annotations
@@ -56,3 +70,17 @@ export const ShardGroup = ServiceMap.Reference<(entityId: EntityId) => string>(
 export const ClientTracingEnabled = ServiceMap.Reference<boolean>("effect/cluster/ClusterSchema/ClientTracingEnabled", {
   defaultValue: constTrue
 })
+
+/**
+ * Dynamically transform the request annotations based on the request.
+ * This only applies to the requests handled by the Entity, not the client.
+ *
+ * @since 4.0.0
+ * @category Annotations
+ */
+export const Dynamic = ServiceMap.Reference<
+  (annotations: ServiceMap.ServiceMap<never>, request: Request<Rpc.AnyWithProps>) => ServiceMap.ServiceMap<never>
+>(
+  "effect/cluster/ClusterSchema/Dynamic",
+  { defaultValue: () => identity }
+)

package/src/unstable/cluster/ClusterWorkflowEngine.ts

@@ -6,7 +6,10 @@ import * as Duration from "../../Duration.ts"
 import * as Effect from "../../Effect.ts"
 import * as Exit from "../../Exit.ts"
 import * as Fiber from "../../Fiber.ts"
+import { constFalse } from "../../Function.ts"
+import * as Latch from "../../Latch.ts"
 import * as Layer from "../../Layer.ts"
+import * as Option from "../../Option.ts"
 import * as PrimaryKey from "../../PrimaryKey.ts"
 import * as RcMap from "../../RcMap.ts"
 import type * as Record from "../../Record.ts"
@@ -15,7 +18,7 @@ import * as Schema from "../../Schema.ts"
 import type * as Scope from "../../Scope.ts"
 import * as ServiceMap from "../../ServiceMap.ts"
 import * as Rpc from "../rpc/Rpc.ts"
-import * as RpcServer from "../rpc/RpcServer.ts"
+import { ClientAbort } from "../rpc/RpcSchema.ts"
 import * as Activity from "../workflow/Activity.ts"
 import * as DurableClock from "../workflow/DurableClock.ts"
 import * as DurableDeferred from "../workflow/DurableDeferred.ts"
@@ -64,7 +67,9 @@ export const make = Effect.gen(function*() {
       | Rpc.Rpc<"deferred", Schema.Struct<{ name: typeof Schema.String; exit: typeof ExitUnknown }>, typeof ExitUnknown>
       | Rpc.Rpc<
         "activity",
-        Schema.Struct<{ name: typeof Schema.String; attempt: typeof Schema.Number }>,
+        Schema.Struct<
+          { name: typeof Schema.String; attempt: typeof Schema.Number; withTransaction: typeof Schema.Boolean }
+        >,
         Schema.declare<Workflow.Result<any, any>>
       >
       | Rpc.Rpc<"resume", Schema.Struct<{}>>
@@ -106,7 +111,7 @@ export const make = Effect.gen(function*() {
     readonly services: ServiceMap.ServiceMap<any>
   }>()
   const interruptedActivities = new Set<string>()
-  const activityLatches = new Map<string, Effect.Latch>()
+  const activityLatches = new Map<string, Latch.Latch>()
   const clients = yield* RcMap.make({
     lookup: Effect.fnUntraced(function*(workflowName: string) {
       const entity = entities.get(workflowName)
@@ -149,8 +154,9 @@ export const make = Effect.gen(function*() {
     const replies = yield* storage.repliesForUnfiltered([requestId])
     const last = replies[replies.length - 1]
     if (last && last._tag === "WithExit") {
-      return last as WithExitEncoded<Workflow.ResultEncoded<any, any>>
+      return Option.some(last as WithExitEncoded<Workflow.ResultEncoded<any, any>>)
     }
+    return Option.none<WithExitEncoded<Workflow.ResultEncoded<any, any>>>()
   })
 
   const requestReply = Effect.fnUntraced(function*(options: {
@@ -161,10 +167,10 @@ export const make = Effect.gen(function*() {
     readonly id: string
   }) {
     const requestId = yield* requestIdFor(options)
-    if (requestId === undefined) {
-      return undefined
+    if (Option.isNone(requestId)) {
+      return Option.none<WithExitEncoded<Workflow.ResultEncoded<any, any>>>()
     }
-    return yield* replyForRequestId(requestId)
+    return yield* replyForRequestId(requestId.value)
   })
 
   const resetActivityAttempt = Effect.fnUntraced(
@@ -181,8 +187,8 @@ export const make = Effect.gen(function*() {
         tag: "activity",
         id: activityPrimaryKey(options.activity.name, options.attempt)
       })
-      if (requestId === undefined) return
-      yield* sharding.reset(requestId)
+      if (Option.isNone(requestId)) return
+      yield* sharding.reset(requestId.value)
     },
     Effect.retry({
       times: 3,
@@ -217,13 +223,13 @@ export const make = Effect.gen(function*() {
       id: ""
     })
 
-    const maybeSuspended =
-      maybeReply && maybeReply.exit._tag === "Success" && maybeReply.exit.value._tag === "Suspended"
-        ? maybeReply
-        : undefined
+    const maybeSuspended = Option.filter(
+      maybeReply,
+      (reply) => reply.exit._tag === "Success" && reply.exit.value._tag === "Suspended"
+    )
 
-    if (maybeSuspended === undefined) return
-    yield* sharding.reset(Snowflake.Snowflake(maybeSuspended.requestId))
+    if (Option.isNone(maybeSuspended)) return
+    yield* sharding.reset(Snowflake.Snowflake(maybeSuspended.value.requestId))
     yield* sharding.pollStorage
   })
 
@@ -238,13 +244,13 @@ export const make = Effect.gen(function*() {
       tag: "resume",
       id: ""
     })
-    if (requestId === undefined) {
+    if (Option.isNone(requestId)) {
       const client = (yield* RcMap.get(clientsPartial, options.workflowName))(options.executionId)
       return yield* client.resume({} as any, { discard: true })
     }
-    const reply = yield* replyForRequestId(requestId)
-    if (reply === undefined) return
-    yield* sharding.reset(requestId)
+    const reply = yield* replyForRequestId(requestId.value)
+    if (Option.isNone(reply)) return
+    yield* sharding.reset(requestId.value)
   }, Effect.scoped)
 
   const engine = WorkflowEngine.makeUnsafe({
@@ -271,7 +277,7 @@ export const make = Effect.gen(function*() {
                     }
                     return engine.deferredResult(InterruptSignal).pipe(
                       Effect.flatMap((maybeExit) => {
-                        if (maybeExit === undefined) {
+                        if (Option.isNone(maybeExit)) {
                           return Effect.void
                         }
                         instance.suspended = false
@@ -297,7 +303,7 @@ export const make = Effect.gen(function*() {
                 return Effect.gen(function*() {
                   let entry = activities.get(activityId)
                   while (!entry) {
-                    const latch = Effect.makeLatchUnsafe()
+                    const latch = Latch.makeUnsafe()
                     activityLatches.set(activityId, latch)
                     yield* latch.await
                     entry = activities.get(activityId)
@@ -314,7 +320,7 @@ export const make = Effect.gen(function*() {
                     // we only want to store interrupts as suspends when the
                     // client requested it
                     const suspend = cause.reasons.some((f) =>
-                      f._tag === "Interrupt" && f.fiberId === RpcServer.fiberIdClientInterrupt
+                      f._tag === "Interrupt" && f.annotations.has(ClientAbort.key)
                     )
                     if (suspend) {
                       interruptedActivities.add(activityId)
@@ -372,12 +378,12 @@ export const make = Effect.gen(function*() {
         tag: "run",
         id: ""
       })
-      if (!reply) return undefined
-      const exit = yield* (Schema.decodeEffect(exitSchema)(reply.exit) as Effect.Effect<
+      if (Option.isNone(reply)) return Option.none()
+      const exit = yield* (Schema.decodeUnknownEffect(exitSchema)(reply.value.exit) as Effect.Effect<
         Exit.Exit<any, any>,
         Schema.SchemaError
       >)
-      return yield* exit
+      return Option.some(yield* exit)
     }, Effect.orDie),
 
     interrupt: Effect.fnUntraced(
@@ -391,10 +397,11 @@ export const make = Effect.gen(function*() {
           id: ""
         })
 
-        const nonSuspendedReply = reply && (reply.exit._tag !== "Success" || reply.exit.value._tag !== "Suspended")
-          ? reply
-          : undefined
-        if (nonSuspendedReply !== undefined) {
+        const nonSuspendedReply = Option.filter(
+          reply,
+          (reply) => reply.exit._tag !== "Success" || reply.exit.value._tag !== "Suspended"
+        )
+        if (Option.isSome(nonSuspendedReply)) {
           return
         }
 
@@ -431,7 +438,13 @@ export const make = Effect.gen(function*() {
               activityLatches.delete(activityId)
             }
           }
-          const result = yield* Effect.orDie(client.activity({ name: activity.name, attempt }))
+          const result = yield* Effect.orDie(
+            client.activity({
+              name: activity.name,
+              attempt,
+              withTransaction: ServiceMap.get(activity.annotations, ClusterSchema.WithTransaction)
+            })
+          )
           // If the activity has suspended and did not execute, we need to resume
           // it by resetting the attempt and re-executing.
           if (result._tag === "Suspended" && (activities.has(activityId) || interruptedActivities.has(activityId))) {
@@ -462,13 +475,15 @@ export const make = Effect.gen(function*() {
           })
         ),
         Effect.map((reply) => {
-          if (reply === undefined) {
-            return undefined
+          if (Option.isNone(reply)) {
+            return Option.none<Exit.Exit<unknown, unknown>>()
           }
-          const decoded = decodeDeferredWithExit(reply as any)
-          return decoded.exit._tag === "Success"
-            ? decoded.exit.value
-            : decoded.exit
+          const decoded = decodeDeferredWithExit(reply.value as any)
+          return Option.some(
+            decoded.exit._tag === "Success"
+              ? decoded.exit.value
+              : decoded.exit
+          )
         }),
         Effect.retry({
           while: (e) => e._tag === "PersistenceError",
@@ -526,7 +541,10 @@ const ExitUnknown = Schema.Exit(AnyOrVoid, AnyOrVoid, Schema.Any)
 const ActivityRpc = Rpc.make("activity", {
   payload: {
     name: Schema.String,
-    attempt: Schema.Number
+    attempt: Schema.Number,
+    withTransaction: Schema.Boolean.pipe(
+      Schema.withDecodingDefault(constFalse)
+    )
   },
   primaryKey: ({ attempt, name }) => activityPrimaryKey(name, attempt),
   success: Workflow.Result({
@@ -535,6 +553,13 @@ const ActivityRpc = Rpc.make("activity", {
   })
 })
   .annotate(ClusterSchema.Persisted, true)
+  .annotate(
+    ClusterSchema.Dynamic,
+    (annotations, request) =>
+      (request.payload as any).withTransaction
+        ? ServiceMap.add(annotations, ClusterSchema.WithTransaction, true)
+        : annotations
+  )
 
 const DeferredRpc = Rpc.make("deferred", {
   payload: {

package/src/unstable/cluster/DeliverAt.ts

@@ -30,7 +30,7 @@ export const isDeliverAt = (self: unknown): self is DeliverAt => hasProperty(sel
  */
 export const toMillis = (self: unknown): number | null => {
   if (isDeliverAt(self)) {
-    return self[symbol]().epochMillis
+    return self[symbol]().epochMilliseconds
   }
   return null
 }