effect 4.0.4 → 4.0.6

package/src/cli/internal/completions/powershell.ts

@@ -8,6 +8,7 @@
  * @internal
  */
 import type * as Completions from "../../Completions.ts"
+import { negatedName } from "./descriptor.ts"
 
 /**
  * Encode non-ASCII and control characters as `[char]` code units. Windows
@@ -46,10 +47,15 @@ const valueFields = (type: Completions.FlagType | Completions.ArgumentType): str
   `values = ${psArray(type._tag === "Choice" ? type.values : [])}; ` +
   `pathType = ${type._tag === "Path" ? quotePs(type.pathType) : "$null"}`
 
-const flagEntry = (flag: Completions.FlagDescriptor): string =>
-  `@{ name = ${quotePs(flag.name)}; forms = ${psArray(flagForms(flag))}; ` +
-  `takesValue = $${flag.type._tag !== "Boolean"}; ${valueFields(flag.type)}; ` +
-  `description = ${psOptional(flag.description)} }`
+const flagEntry = (flag: Completions.FlagDescriptor): string => {
+  const negation = negatedName(flag)
+  return `@{ name = ${quotePs(flag.name)}; forms = ${psArray(flagForms(flag))}; ` +
+    `takesValue = $${flag.type._tag !== "Boolean"}; ` +
+    (negation === undefined ? "" : `negation = ${quotePs(`--${negation}`)}; `) +
+    (flag.optionalValue === true ? `optionalValue = $true; ` : "") +
+    `${valueFields(flag.type)}; ` +
+    `description = ${psOptional(flag.description)} }`
+}
 
 const argumentEntry = (argument: Completions.ArgumentDescriptor): string =>
   `@{ name = ${quotePs(argument.name)}; variadic = $${argument.variadic}; ${valueFields(argument.type)}; ` +
@@ -152,10 +158,10 @@ const completer = (dataName: string): string =>
       foreach ($form in $flag.forms) {
         & $add $form 'ParameterName' $flag.description $typed ''
       }
-      if (-not $flag.takesValue) {
+      if ($flag.negation) {
         $tooltip = $null
         if ($flag.description) { $tooltip = 'Disable ' + $flag.name }
-        & $add ('--no-' + $flag.name) 'ParameterName' $tooltip $typed ''
+        & $add $flag.negation 'ParameterName' $tooltip $typed ''
       }
     }
   }
@@ -226,16 +232,22 @@ const completer = (dataName: string): string =>
       foreach ($form in $forms) {
         $pending = $null
         $flag = $lookup[$form]
-        if ($null -eq $flag) {
-          if ($form.StartsWith('--no-')) {
-            $name = $form.Substring(5)
-            $flag = $lookup['--' + $name]
-            if ($null -ne $flag -and -not $flag.takesValue -and $flag.name -ceq $name) { $used[$name] = $true }
+        # As in the CLI parser, a negation wins over an alias but not over a
+        # canonical name.
+        if ($null -eq $flag -or $form -cne ('--' + $flag.name)) {
+          $negated = $null
+          foreach ($candidate in $context.flags) {
+            if ($candidate.negation -ceq $form) { $negated = $candidate }
+          }
+          if ($null -ne $negated) {
+            $used[$negated.name] = $true
+            continue
           }
-          continue
         }
+        if ($null -eq $flag) { continue }
         $used[$flag.name] = $true
-        if (-not $hasValue) { $pending = $flag }
+        # A flag with an optional value only takes a value attached with '='.
+        if (-not $hasValue -and -not $flag.optionalValue) { $pending = $flag }
       }
       continue
     }

package/src/cli/internal/completions/zsh.ts

@@ -7,6 +7,7 @@
  * @internal
  */
 import type * as Completions from "../../Completions.ts"
+import { negatedName } from "./descriptor.ts"
 
 // ---------------------------------------------------------------------------
 // Helpers
@@ -22,15 +23,16 @@ const escapeZshChoice = (s: string): string => s.replace(/[^A-Za-z0-9_.,/@%+-]/g
 const sanitize = (s: string): string => s.replace(/[^a-zA-Z0-9_]/g, "_")
 
 /**
- * All forms of a flag (--name, -alias, --no-name) for the exclusion group.
+ * All forms of a flag (--name, -alias, negation) for the exclusion group.
  */
 const allForms = (flag: Completions.FlagDescriptor): Array<string> => {
   const forms: Array<string> = [`--${flag.name}`]
   for (const alias of flag.aliases) {
     forms.push(alias.length === 1 ? `-${alias}` : `--${alias}`)
   }
-  if (flag.type._tag === "Boolean") {
-    forms.push(`--no-${flag.name}`)
+  const negation = negatedName(flag)
+  if (negation !== undefined) {
+    forms.push(`--${negation}`)
   }
   return forms
 }
@@ -72,22 +74,27 @@ const argAction = (type: Completions.ArgumentType): string => {
 const flagSpecs = (flag: Completions.FlagDescriptor): Array<string> => {
   const specs: Array<string> = []
   const desc = flag.description ? `[${escapeZshExplanation(flag.description)}]` : ""
-  const action = valueAction(flag.type)
+  // An optional value must follow `=` in the same word (`--name=-`), and `::`
+  // marks it optional.
+  const optional = flag.optionalValue === true && flag.type._tag !== "Boolean"
+  const valueSuffix = optional ? "=-" : ""
+  const action = optional ? `:${valueAction(flag.type)}` : valueAction(flag.type)
   const excl = `(${allForms(flag).join(" ")})`
 
   // Primary long name
-  specs.push(`'${excl}--${flag.name}${desc}${action}'`)
+  specs.push(`'${excl}--${flag.name}${valueSuffix}${desc}${action}'`)
 
   // Aliases
   for (const alias of flag.aliases) {
     const prefix = alias.length === 1 ? "-" : "--"
-    specs.push(`'${excl}${prefix}${alias}${desc}${action}'`)
+    specs.push(`'${excl}${prefix}${alias}${valueSuffix}${desc}${action}'`)
   }
 
   // Boolean negation
-  if (flag.type._tag === "Boolean") {
+  const negation = negatedName(flag)
+  if (negation !== undefined) {
     const negDesc = flag.description ? `[${escapeZshExplanation(`Disable ${flag.name}`)}]` : ""
-    specs.push(`'${excl}--no-${flag.name}${negDesc}'`)
+    specs.push(`'${excl}--${negation}${negDesc}'`)
   }
 
   return specs

package/src/cli/internal/formatter.ts

@@ -0,0 +1,18 @@
+import * as Context from "../../Context.ts"
+import * as Effect from "../../Effect.ts"
+import * as CliOutput from "../CliOutput.ts"
+import * as TerminalCapabilities from "../TerminalCapabilities.ts"
+
+/**
+ * The formatter for built-in command output. An installed `CliOutput.Formatter`
+ * wins, otherwise the default formatter colors when `TerminalCapabilities`
+ * says it can.
+ *
+ * @internal
+ */
+export const resolveFormatter: Effect.Effect<CliOutput.Formatter> = Effect.contextWith((context) =>
+  Effect.succeed(
+    Context.getOrUndefined(context, CliOutput.Formatter) ??
+      CliOutput.defaultFormatter({ colors: Context.get(context, TerminalCapabilities.TerminalCapabilities).canColor })
+  )
+)

package/src/cli/internal/lexer.ts

@@ -58,8 +58,12 @@ const lexTokens = (args: ReadonlyArray<string>): ReadonlyArray<Token> => {
       const equalIndex = arg.indexOf("=")
       if (equalIndex !== -1) {
         const name = arg.slice(2, equalIndex)
-        const value = arg.slice(equalIndex + 1)
-        tokens.push({ _tag: "LongOption", name, raw: arg, value })
+        if (name === "") {
+          tokens.push({ _tag: "Value", value: arg })
+        } else {
+          const value = arg.slice(equalIndex + 1)
+          tokens.push({ _tag: "LongOption", name, raw: arg, value })
+        }
       } else {
         tokens.push({ _tag: "LongOption", name: arg.slice(2), raw: arg })
       }
@@ -67,9 +71,12 @@ const lexTokens = (args: ReadonlyArray<string>): ReadonlyArray<Token> => {
       const flags = arg.slice(1)
       const equalIndex = flags.indexOf("=")
       if (equalIndex !== -1) {
-        const flag = flags.slice(0, equalIndex)
-        const value = flags.slice(equalIndex + 1)
-        tokens.push({ _tag: "ShortOption", flag, raw: `-${flag}`, value })
+        const chars = Array.from(flags.slice(0, equalIndex))
+        const flag = chars.pop() ?? ""
+        for (const ch of chars) {
+          tokens.push({ _tag: "ShortOption", flag: ch, raw: `-${ch}` })
+        }
+        tokens.push({ _tag: "ShortOption", flag, raw: `-${flag}`, value: flags.slice(equalIndex + 1) })
       } else {
         for (const ch of flags) {
           tokens.push({ _tag: "ShortOption", flag: ch, raw: `-${ch}` })

package/src/cli/internal/parser.ts

@@ -125,6 +125,8 @@ type FlagRegistry = {
   readonly params: ReadonlyArray<FlagParam>
   /** Maps canonical names and aliases → flag param */
   readonly index: Map<string, FlagParam>
+  /** Maps negated names of boolean flags → flag param */
+  readonly negations: Map<string, FlagParam>
 }
 
 /**
@@ -229,12 +231,22 @@ const makeCursor = (tokens: ReadonlyArray<Token>): TokenCursor => {
 /* Flag Registry                                                              */
 /* ========================================================================== */
 
+/**
+ * Long name that sets a boolean flag to `false`, or `undefined` when the flag
+ * has no negated form.
+ */
+const negatedName = (param: FlagParam): string | undefined =>
+  !Primitive.isBoolean(param.primitiveType) || param.negation === false
+    ? undefined
+    : param.negation ?? `no-${param.name}`
+
 /**
  * Creates a registry for O(1) flag lookup by name or alias.
  * @internal
  */
 export const createFlagRegistry = (params: ReadonlyArray<FlagParam>): FlagRegistry => {
   const index = new Map<string, FlagParam>()
+  const negations = new Map<string, FlagParam>()
 
   for (const param of params) {
     if (index.has(param.name)) {
@@ -250,9 +262,19 @@ export const createFlagRegistry = (params: ReadonlyArray<FlagParam>): FlagRegist
       }
       index.set(alias, param)
     }
+
+    const negation = negatedName(param)
+    if (negation !== undefined) {
+      if (negations.has(negation)) {
+        throw new Error(
+          `Duplicate negation "${negation}" in command definition (conflicts with "${negations.get(negation)!.name}")`
+        )
+      }
+      negations.set(negation, param)
+    }
   }
 
-  return { params, index }
+  return { params, index, negations }
 }
 
 const buildSubcommandIndex = (
@@ -362,14 +384,11 @@ const resolveFlag = (
     }
   }
 
-  if (token._tag === "LongOption" && token.name.startsWith("no-")) {
-    const canonicalName = token.name.slice(3)
-    const param = registry.index.get(canonicalName)
-    if (param && param.name === canonicalName && Primitive.isBoolean(param.primitiveType)) {
-      return {
-        param,
-        negated: true
-      }
+  const negated = token._tag === "LongOption" ? registry.negations.get(token.name) : undefined
+  if (negated) {
+    return {
+      param: negated,
+      negated: true
     }
   }
 
@@ -425,8 +444,9 @@ const asBooleanLiteral = (token: Token | undefined): string | undefined =>
  *
  * Value resolution order:
  * 1. Inline value: --flag=value or -f=value
- * 2. Boolean special case: implicit "true" or explicit boolean literal
- * 3. Next token: consume following Value token if present
+ * 2. Optional value: the flag's configured value, without consuming a token
+ * 3. Boolean special case: implicit "true" or explicit boolean literal
+ * 4. Next token: consume following Value token if present
  */
 const consumeFlagValue = (
   cursor: TokenCursor,
@@ -465,7 +485,7 @@ const consumeFlagValueWithTokens = (
       }
     }
 
-    const literal = asBooleanLiteral(cursor.peek())
+    const literal = spec.optionalValue === undefined ? asBooleanLiteral(cursor.peek()) : undefined
     if (literal !== undefined) {
       const literalToken = cursor.take()
       return {
@@ -490,6 +510,14 @@ const consumeFlagValueWithTokens = (
     }
   }
 
+  if (spec.optionalValue !== undefined) {
+    return {
+      _tag: "Value",
+      value: spec.optionalValue,
+      tokens: []
+    }
+  }
+
   // Boolean flags: check for explicit literal or default to "true"
   if (Primitive.isBoolean(spec.primitiveType)) {
     const literal = asBooleanLiteral(cursor.peek())
@@ -731,8 +759,9 @@ const createUnrecognizedFlagError = (
     // that was intentionally kept out of --help.
     if (p.hidden) continue
     validNames.push(p.name)
-    if (Primitive.isBoolean(p.primitiveType)) {
-      validNames.push(`no-${p.name}`)
+    const negation = negatedName(p)
+    if (negation !== undefined) {
+      validNames.push(negation)
     }
     for (const alias of p.aliases) {
       validNames.push(alias)

package/src/cli/internal/wizard.ts

@@ -171,8 +171,9 @@ const promptParam = Effect.fnUntraced(
       return values
     }
     // Inline option-looking values so the lexer cannot interpret them as flags or the -- delimiter.
+    // Flags with an optional value only accept an inline value.
     return values.flatMap((value) =>
-      value.value.startsWith("-") && value.value.length > 1
+      single.optionalValue !== undefined || (value.value.startsWith("-") && value.value.length > 1)
         ? [commandLineArg(`--${single.name}=${value.value}`, `--${single.name}=${value.displayValue}`)]
         : [commandLineArg(`--${single.name}`), value]
     )

package/src/cluster/ClusterCron.ts

@@ -7,9 +7,15 @@
  * for distributed maintenance work where the job should be owned by the cluster
  * rather than by every runner independently.
  *
+ * With `calculateNextRunFromPrevious`, every run is processed by a single
+ * entity per cron job, so runs never overlap and are caught up in order. The
+ * scheduled time of the current run is available through
+ * `CurrentScheduledTime`.
+ *
  * @stability unstable
  * @since 4.0.0
  */
+import * as Context from "../Context.ts"
 import * as Cron from "../Cron.ts"
 import * as DateTime from "../DateTime.ts"
 import * as Duration from "../Duration.ts"
@@ -29,6 +35,23 @@ import * as Entity from "./Entity.ts"
 import type { Sharding } from "./Sharding.ts"
 import * as Singleton from "./Singleton.ts"
 
+/**
+ * Service tag for the scheduled time of the cron run currently executing.
+ *
+ * **When to use**
+ *
+ * Use to read the time the current run was scheduled for, inside the
+ * `execute` effect of `make`.
+ *
+ * @stability unstable
+ * @category services
+ * @since 4.0.0
+ */
+export class CurrentScheduledTime extends Context.Service<
+  CurrentScheduledTime,
+  DateTime.Utc
+>()("effect/cluster/ClusterCron/CurrentScheduledTime") {}
+
 /**
  * Creates a layer that runs a cron job through the cluster sharding system.
  *
@@ -60,6 +83,11 @@ export const make = <E, R>(options: {
    *
    * Defaults to `false`, meaning the next run will be calculated from the
    * current time.
+   *
+   * When enabled, all runs are processed one at a time by a single entity, so
+   * missed runs are caught up in order without overlapping. A run that fails
+   * is retried in place and blocks later runs until it succeeds or is older
+   * than `skipIfOlderThan`.
    */
   readonly calculateNextRunFromPrevious?: boolean | undefined
 
@@ -76,26 +104,42 @@ export const make = <E, R>(options: {
    * Defaults to "1 day".
    */
   readonly skipIfOlderThan?: Duration.Input | undefined
-}): Layer.Layer<never, never, Sharding | Exclude<R, Scope>> => {
+}): Layer.Layer<never, never, Sharding | Exclude<Exclude<R, CurrentScheduledTime>, Scope>> => {
+  const fromPrevious = options.calculateNextRunFromPrevious === true
+  const nextRun = (after: DateTime.Utc) => DateTime.fromDateUnsafe(Cron.next(options.cron, after))
+
   const CronEntity = Entity.make(`ClusterCron/${options.name}`, [
     Rpc.make("run", {
       payload: CronPayload
     })
       .annotate(Persisted, true)
-      .annotate(Uninterruptible, true)
+      .annotate(Uninterruptible, true),
+    Rpc.make("start").annotate(Persisted, true)
   ])
     .annotate(ClusterSchema.ShardGroup, () => options.shardGroup ?? "default")
     .annotate(ClusterSchema.ClientTracingEnabled, false)
 
+  // with `calculateNextRunFromPrevious`, every run shares the executor address
+  const send = (dateTime: DateTime.Utc) =>
+    Effect.flatMap(CronEntity.client, (makeClient) =>
+      fromPrevious
+        ? makeClient(executorId).run(new CronPayload({ dateTime, executor: true }), { discard: true })
+        : makeClient(DateTime.formatIso(dateTime)).run(new CronPayload({ dateTime }), { discard: true }))
+
+  const schedule = (dateTime: DateTime.Utc) => send(dateTime).pipe(withRetry("Failed to schedule next run, retrying"))
+
   const InitialRun = Singleton.make(
     `ClusterCron/${options.name}`,
-    Effect.gen(function*() {
-      const now = yield* DateTime.now
-      const next = DateTime.fromDateUnsafe(Cron.next(options.cron, now))
-      const entityId = options.calculateNextRunFromPrevious ? "initial" : DateTime.formatIso(next)
-      const client = (yield* CronEntity.client)(entityId)
-      yield* client.run({ dateTime: next }, { discard: true })
-    }),
+    fromPrevious
+      // the executor schedules the next run if its chain has been lost.
+      // `start` has no primary key, so each retry is a new message
+      ? Effect.flatMap(CronEntity.client, (makeClient) => makeClient(executorId).start()).pipe(
+        withRetry("Failed to start cron job, retrying")
+      )
+      : Effect.flatMap(
+        DateTime.now,
+        (now) => send(nextRun(now)).pipe(withRetry("Failed to schedule initial run, retrying"))
+      ),
     { shardGroup: options.shardGroup }
   )
 
@@ -104,61 +148,76 @@ export const make = <E, R>(options: {
     Option.getOrElse(() => Duration.days(1))
   )
 
-  const effect = Effect.fnUntraced(function*(dateTime: DateTime.Utc) {
+  const execute = Effect.fnUntraced(function*(dateTime: DateTime.Utc) {
     const now = yield* DateTime.now
     if (DateTime.isLessThan(dateTime, DateTime.subtractDuration(now, skipIfOlderThan))) {
       return
     }
-    return yield* options.execute
+    return yield* Effect.provideService(options.execute, CurrentScheduledTime, dateTime)
   }, Effect.orDie)
 
   const EntityLayer = CronEntity.toLayer(Effect.gen(function*() {
-    const makeClient = yield* CronEntity.client
+    const address = yield* Entity.CurrentAddress
+    // runs are processed one at a time, so a run processed before `start`
+    // means the chain is alive
+    let processedRun = false
     return {
-      run: (request) =>
-        Effect.onExitPrimitive(
-          effect(request.payload.dateTime),
-          Effect.fnUntraced(function*(exit) {
-            if (Exit.isFailure(exit)) {
-              yield* Effect.logWarning(exit.cause)
-            }
-            const now = yield* DateTime.now
-            const next = DateTime.fromDateUnsafe(Cron.next(
-              options.cron,
-              options.calculateNextRunFromPrevious ? request.payload.dateTime : now
-            ))
-            const client = makeClient(DateTime.formatIso(next))
-            return yield* client.run({ dateTime: next }, { discard: true }).pipe(
-              Effect.tapCause((cause) => Effect.logWarning("Failed to schedule next run, retrying", cause)),
-              Effect.sandbox,
-              Effect.retry(retryPolicy),
-              Effect.orDie
-            )
-          }),
+      run: (request) => {
+        const dateTime = request.payload.dateTime
+        if (fromPrevious && address.entityId !== executorId) {
+          // a run scheduled by an earlier release joins the executor's chain
+          return schedule(dateTime)
+        }
+        processedRun = true
+        return Effect.onExitPrimitive(
+          execute(dateTime),
+          (exit) =>
+            Effect.andThen(
+              Exit.isFailure(exit) ? Effect.logWarning(exit.cause) : Effect.void,
+              fromPrevious ? schedule(nextRun(dateTime)) : Effect.flatMap(DateTime.now, (now) => schedule(nextRun(now)))
+            ),
           true
         ).pipe(
           Effect.annotateLogs({
             module: "effect/cluster/ClusterCron",
             name: options.name,
-            dateTime: request.payload.dateTime
+            dateTime
           })
         )
+      },
+      start: () =>
+        processedRun
+          ? Effect.void
+          // deduplicated against the pending run if the chain is alive
+          : Effect.flatMap(DateTime.now, (now) => schedule(nextRun(now)))
     }
   }))
 
   return Layer.merge(InitialRun, EntityLayer)
 }
 
+const executorId = "executor"
+
 const retryPolicy = Schedule.min([
   Schedule.exponential(200, 1.5),
   Schedule.spaced("1 minute")
 ])
 
+const withRetry = (message: string) => <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, never, R> =>
+  self.pipe(
+    Effect.tapCause((cause) => Effect.logWarning(message, cause)),
+    Effect.sandbox,
+    Effect.retry(retryPolicy),
+    Effect.orDie
+  )
+
 class CronPayload extends Schema.Class<CronPayload>("effect/cluster/ClusterCron/CronPayload")({
-  dateTime: Schema.DateTimeUtc
+  dateTime: Schema.DateTimeUtc,
+  // set for runs sent to the executor, which share one entity address
+  executor: Schema.optional(Schema.Boolean)
 }) {
   [PrimaryKey.symbol]() {
-    return ""
+    return this.executor ? DateTime.formatIso(this.dateTime) : ""
   }
   [DeliverAt.symbol]() {
     return this.dateTime