@neontechspace/fluxerly 1000.0.0-nightly.12

package/src/internal/binding/execute.ts

@@ -0,0 +1,221 @@
+/**
+ * Default execution: Runs shared Effect operations for the default API and converts their exits to neverthrow results.
+ * Invariant: Expected failures become Err values, cancellation becomes CancelledError after cleanup, and defects,
+ * including cleanup defects combined with another failure, throw or reject as SdkDefect naming the public operation.
+ * Reading the caller options and calling the caller signal listener methods are application code, so their throws are
+ * application faults.
+ * Implements [SDK contracts: Results and failures](/docs/SDK-CONTRACTS.md#results-and-failures)
+ */
+import * as Cause from "effect/Cause"
+import * as Effect from "effect/Effect"
+import * as Exit from "effect/Exit"
+import { err, ok, ResultAsync, type Result } from "neverthrow"
+import { operationSignalError } from "#sdk/internal/operation-signal"
+import { currentRejectionScope, withRejectionScope } from "#sdk/internal/rejection-scope"
+import { causeReasons, defectReason, inputDefect, readCaller, thrownReason } from "#sdk/internal/defects"
+import {
+    CancelledError,
+    SdkDefect,
+    type ClientClosedError,
+    type ConfigurationError,
+    type ConnectError,
+    type Operation,
+} from "#sdk/errors"
+import type { MemberChunkError } from "#sdk/member-chunks"
+import type { CountOperationError } from "#sdk/counts"
+import type { BotApplicationOperationError } from "#sdk/application"
+import type { PresenceError } from "#sdk/presence"
+import type { UserOperationError } from "#sdk/users"
+import type { WebhookOperationError } from "#sdk/webhooks"
+import type { PaginationError, PaginationOperation } from "#sdk/pagination"
+import type { MessageCore, MessageOperationOptions } from "#sdk/messages"
+import type { ClientOwner } from "#sdk/internal/client"
+import type { Pagination } from "#sdk/internal/pagination"
+import type { AttachmentDownloadFailure, AttachmentRefreshFailure } from "#sdk/attachments"
+import type { CriticalWorkerStoppedError } from "#sdk/bot-runner"
+import type { OAuthOperationFailure } from "#sdk/oauth"
+import type { OperationOptions } from "#sdk/client"
+import type { InstanceResolveError } from "#sdk/instance"
+import type { ChannelOperationError } from "#sdk/channels"
+import type { GuildOperationError } from "#sdk/guilds"
+import type { CollectorError } from "#sdk/collectors"
+import type { EventReadError, EventWaitFailure, MessageError, MessageOperationError } from "#sdk/message-errors"
+import type { MessageCleanupError } from "#sdk/message-cleanup"
+import type { RestRequestFailure } from "#sdk/rest"
+
+/** Every expected failure a default operation can return */
+export type OperationFailure =
+    | ConfigurationError
+    | CancelledError
+    | ConnectError
+    | CriticalWorkerStoppedError
+    | InstanceResolveError
+    | EventReadError
+    | EventWaitFailure
+    | MessageError
+    | MessageOperationError
+    | MessageCleanupError
+    | CollectorError
+    | GuildOperationError
+    | ChannelOperationError
+    | WebhookOperationError
+    | UserOperationError
+    | BotApplicationOperationError
+    | CountOperationError
+    | MemberChunkError
+    | PresenceError
+    | PaginationError
+    | AttachmentDownloadFailure
+    | AttachmentRefreshFailure
+    | OAuthOperationFailure
+    | RestRequestFailure
+
+/** Start one operation now and settle its ResultAsync after the Effect and required cleanup finish */
+export const executeOperation = <A, E extends OperationFailure>(
+    effect: Effect.Effect<A, E>,
+    operation: Operation,
+    options?: OperationOptions,
+) => {
+    let signal: OperationOptions["signal"]
+    let abort: (() => void) | undefined
+    let registered = false
+    let invalidSignal: ConfigurationError | undefined
+    let aborted = false
+    try {
+        // Reading caller options and the signal state can throw only from application getters or proxies
+        signal = options?.signal
+        invalidSignal = operationSignalError(signal)
+        aborted = invalidSignal === undefined && signal?.aborted === true
+    } catch (error) {
+        return new ResultAsync<A, E | CancelledError | ConfigurationError>(
+            Promise.reject(new SdkDefect(operation, [defectReason(error, "application")])),
+        )
+    }
+    try {
+        if (invalidSignal)
+            return new ResultAsync<A, E | CancelledError | ConfigurationError>(Promise.resolve(err(invalidSignal)))
+        if (aborted)
+            return new ResultAsync<A, E | CancelledError | ConfigurationError>(
+                Promise.resolve(err(new CancelledError(operation))),
+            )
+        const controller = signal ? new AbortController() : undefined
+        abort = () => controller?.abort()
+        // Read while the calling handler code runs, so a rejection inside a handler is reported once
+        const scope = currentRejectionScope()
+        if (signal) {
+            // Treat registration as owned before calling it: A custom signal can attach then throw
+            registered = true
+            readCaller(() => signal!.addEventListener("abort", abort!, { once: true }))
+        }
+        // Interrupt the operation itself rather than discarding a losing race's cleanup cause
+        return new ResultAsync(
+            (async () => {
+                let exit: Exit.Exit<A, E>
+                try {
+                    exit = await Effect.runPromiseExit(
+                        withRejectionScope(effect, scope),
+                        controller ? { signal: controller.signal } : undefined,
+                    )
+                } catch (error) {
+                    exit = Exit.failCause(Cause.die(error))
+                }
+                if (registered) {
+                    registered = false
+                    try {
+                        signal!.removeEventListener("abort", abort!)
+                    } catch (error) {
+                        exit = Exit.failCause(
+                            Cause.combine(Exit.isFailure(exit) ? exit.cause : Cause.empty, inputDefect(error)),
+                        )
+                    }
+                }
+                return fromExit(exit, operation)
+            })(),
+        )
+    } catch (error) {
+        let cleanupDefect = false
+        let cleanupError: unknown
+        if (registered) {
+            registered = false
+            try {
+                signal!.removeEventListener("abort", abort!)
+            } catch (failure) {
+                cleanupDefect = true
+                cleanupError = failure
+            }
+        }
+        return new ResultAsync<A, E | CancelledError | ConfigurationError>(
+            Promise.reject(
+                new SdkDefect(
+                    operation,
+                    cleanupDefect
+                        ? [thrownReason(error), defectReason(cleanupError, "application")]
+                        : [thrownReason(error)],
+                ),
+            ),
+        )
+    }
+}
+
+/** Convert an exit to a Result, throwing SdkDefect for defects and returning CancelledError for interruption only */
+export function fromExit<A, E extends OperationFailure>(
+    exit: Exit.Exit<A, E>,
+    operation: Operation,
+): Result<A, E | CancelledError> {
+    if (Exit.isSuccess(exit)) return ok(exit.value)
+    if (Cause.hasDies(exit.cause)) {
+        throw new SdkDefect(operation, causeReasons(exit.cause))
+    }
+    const failure = exit.cause.reasons.find((reason) => reason._tag === "Fail")
+    return failure?._tag === "Fail" ? err(failure.error) : err(new CancelledError(operation))
+}
+
+/**
+ * Run a local cache lookup or pure calculation and return its value directly.
+ * Input misuse throws the operation's own error, and defects or interruption throw SdkDefect.
+ * With closedAsAbsent, a closing or closed client has no cache and reads undefined instead of failing
+ */
+export function localValue<A, E>(effect: Effect.Effect<A, E>, operation: Operation, closedAsAbsent: true): A | undefined
+export function localValue<A, E>(effect: Effect.Effect<A, E>, operation: Operation): A
+export function localValue<A, E>(effect: Effect.Effect<A, E>, operation: Operation, closedAsAbsent = false) {
+    const exit = Effect.runSyncExit(effect)
+    if (Exit.isSuccess(exit)) return exit.value
+    if (Cause.hasDies(exit.cause) || Cause.hasInterrupts(exit.cause))
+        throw new SdkDefect(operation, causeReasons(exit.cause))
+    const failure = exit.cause.reasons.find((reason) => reason._tag === "Fail")
+    if (failure?._tag !== "Fail") throw new SdkDefect(operation, causeReasons(exit.cause))
+    if (closedAsAbsent && isClientClosed(failure.error)) return undefined
+    throw failure.error
+}
+
+/** Whether a failure is the closing-client failure that a cache lookup reads as an absent entry */
+export const isClientClosed = (error: unknown): error is ClientClosedError =>
+    typeof error === "object" && error !== null && (error as { _tag?: unknown })._tag === "ClientClosedError"
+
+/** Run a synchronous local lookup. Expected failures return Err, while defects and interruption throw SdkDefect */
+export function lookup<A, E>(effect: Effect.Effect<A, E>, operation: Operation): Result<A, E> {
+    const exit = Effect.runSyncExit(effect)
+    if (Exit.isSuccess(exit)) return ok(exit.value)
+    if (Cause.hasDies(exit.cause) || Cause.hasInterrupts(exit.cause))
+        throw new SdkDefect(operation, causeReasons(exit.cause))
+    const failure = exit.cause.reasons.find((reason) => reason._tag === "Fail")
+    if (failure?._tag === "Fail") return err(failure.error)
+    throw new SdkDefect(operation, causeReasons(exit.cause))
+}
+
+/** What default adapters need from one client: Its owner and executors that provide the client's logger */
+export interface DefaultContext<M extends MessageCore> {
+    readonly owner: ClientOwner<M>
+    /** Start an operation now with the client's logger, honoring options.signal */
+    readonly execute: <A, E extends OperationFailure>(
+        effect: Effect.Effect<A, E>,
+        operation: Operation,
+        options?: OperationOptions,
+    ) => ResultAsync<A, E | CancelledError | ConfigurationError>
+    /** Open a lazy page iterator whose pages start when a loop pulls them */
+    readonly iterate: <A, E extends OperationFailure>(
+        create: (options: MessageOperationOptions) => Effect.Effect<Pagination<A, E>, PaginationError>,
+        operation: PaginationOperation,
+        options?: OperationOptions,
+    ) => AsyncIterable<Result<A, E | PaginationError | CancelledError | ConfigurationError | ClientClosedError>>
+}

package/src/internal/binding/native-adapters.ts

@@ -0,0 +1,199 @@
+/**
+ * Native adapters: The Effect side of operation table entries that need more than the shared Effect, such as
+ * byte streams, member chunk streams, collectors and the cached resolved instance.
+ * Invariant: Adapters start nothing until the caller runs or consumes them, and scoped resources close with the caller's
+ * scope or the stream's consumption. Implements [SDK contracts: Public API model](/docs/SDK-CONTRACTS.md#public-api-model)
+ */
+import * as Deferred from "effect/Deferred"
+import * as Effect from "effect/Effect"
+import type * as Scope from "effect/Scope"
+import * as Stream from "effect/Stream"
+import { AttachmentDownloadError, type Attachment, type AttachmentDownloadOptions } from "#sdk/attachments"
+import type { CacheEntriesOptions, CacheKind } from "#sdk/client"
+import type { InstanceResolveOptions } from "#sdk/instance"
+import type { MemberChunkOptions, MemberChunkQuery } from "#sdk/member-chunks"
+import { ClientClosedError, type ConfigurationError } from "#sdk/errors"
+import {
+    CollectorError,
+    type CollectorFailure,
+    type CollectorResult,
+    type ReactionCollectorResult,
+} from "#sdk/collectors"
+import type { MessageCore, MessageOperationOptions, MessageReference } from "#sdk/messages"
+import type {
+    Collector,
+    CollectorOptions,
+    ReactionCollector,
+    ReactionCollectorOptions,
+} from "#sdk/api/effect/collectors"
+import { collect, type MessageCollector } from "#sdk/internal/collector"
+import { collectReactions, type ReactionCollector as ReactionCollection } from "#sdk/internal/reaction-collector"
+import { effectInstance, type ResolvedInstance } from "#sdk/api/effect/instance"
+import type { ClientOwner } from "#sdk/internal/client"
+import { memberChunkStream } from "#sdk/internal/member-chunks"
+import { readInput } from "#sdk/internal/defects"
+import type { RestRequest } from "#sdk/rest"
+
+export const nativeInstanceResolve = <M extends MessageCore>(owner: ClientOwner<M>) => {
+    // Resolution repeats discovery when needed, but the client keeps returning its first native instance view
+    let instance: ResolvedInstance | undefined
+    return (options?: InstanceResolveOptions) =>
+        owner.instance.resolveInfo(options).pipe(Effect.map((value) => (instance ??= effectInstance(value))))
+}
+
+export const nativeRestRequest =
+    <M extends MessageCore>(owner: ClientOwner<M>) =>
+    <T = unknown>(input: RestRequest) =>
+        owner.request<T>(input)
+
+export const nativeCacheEntries =
+    <M extends MessageCore>(owner: ClientOwner<M>) =>
+    <K extends CacheKind>(kind: K, options?: CacheEntriesOptions) =>
+        // Invalid arguments are misuse, so they become a defect rather than a typed failure
+        owner.cacheEntries(kind, options).pipe(Effect.orDie)
+
+export const nativeCacheClear =
+    <M extends MessageCore>(owner: ClientOwner<M>) =>
+    (kind?: CacheKind) =>
+        owner.clearCache(kind)
+
+export const nativeCacheDelete =
+    <M extends MessageCore>(owner: ClientOwner<M>) =>
+    (kind: CacheKind, key: string) =>
+        owner.deleteCacheEntry(kind, key)
+
+export const nativeMemberChunks =
+    <M extends MessageCore>(owner: ClientOwner<M>) =>
+    (guildId: string, query: MemberChunkQuery, options?: MemberChunkOptions) =>
+        memberChunkStream(owner.memberChunks.open(guildId, query, options))
+
+export const nativeAttachmentStream =
+    <M extends MessageCore>(owner: ClientOwner<M>) =>
+    (attachment: Attachment, options: AttachmentDownloadOptions) => {
+        let consumed = false
+        return Stream.unwrap(
+            Effect.suspend(() => {
+                if (consumed) return Effect.fail(new AttachmentDownloadError({ reason: "busy" }))
+                consumed = true
+                return Effect.gen(function* () {
+                    const source = yield* Effect.acquireRelease(
+                        Effect.interruptible(owner.streamAttachment(attachment, options)),
+                        (source) => source.closeEffect,
+                    )
+                    return Stream.unfold(undefined, () =>
+                        source.next.pipe(
+                            Effect.map((chunk) => (chunk === undefined ? undefined : ([chunk, undefined] as const))),
+                        ),
+                    )
+                })
+            }),
+        )
+    }
+
+function nativeCollector<M extends MessageCore>(source: MessageCollector<M>): Collector<M> {
+    return Object.freeze({
+        close: () => Effect.sync(() => source.stop()),
+        result: () => Deferred.await(source.closed),
+    })
+}
+
+// Keep completed handles outside the registration closure so they do not retain options or the caller's scope
+function nativeReactionCollector(source: ReactionCollection): ReactionCollector {
+    return Object.freeze({
+        close: () => Effect.sync(() => source.stop()),
+        result: () => Deferred.await(source.closed),
+    })
+}
+
+/** Release a scoped collector registration as soon as the collector closes, without waiting for scope closure */
+const releaseWhenClosed = <A, E>(
+    source: { readonly closed: Deferred.Deferred<A, E>; stop(): void },
+    callerScope: Scope.Scope,
+) =>
+    Effect.forkIn(
+        Deferred.await(source.closed).pipe(
+            Effect.asVoid,
+            Effect.interruptible,
+            Effect.onExit(() =>
+                Effect.sync(() => source.stop()).pipe(Effect.andThen(Effect.exit(Deferred.await(source.closed)))),
+            ),
+            // allow-silent: The collector retains its closure outcome for result
+            Effect.catchCause(() => Effect.void),
+        ),
+        callerScope,
+        { uninterruptible: true },
+    )
+
+/**
+ * Keep a runtime registration failure, such as a gateway that is not ready or a client that began shutting down, as a
+ * closed handle whose result fails with it. Shutdown can race a still-running handler that registers, so a closing
+ * client is not misuse. Invalid options are misuse, so they and any other failure become defects rather than handles
+ */
+const openNative = <S, H, R>(
+    open: Effect.Effect<S, ConfigurationError | CollectorFailure, R>,
+    handle: (source: S) => Effect.Effect<H, never, Scope.Scope>,
+    failed: (failure: CollectorFailure) => H,
+): Effect.Effect<H, never, R | Scope.Scope> =>
+    open.pipe(
+        Effect.matchEffect({
+            onFailure: (error) =>
+                error instanceof CollectorError || error instanceof ClientClosedError
+                    ? Effect.succeed(failed(error))
+                    : Effect.die(error),
+            onSuccess: handle,
+        }),
+    )
+
+const failedNative = <A>(failure: CollectorFailure) =>
+    Object.freeze({
+        close: () => Effect.void,
+        result: () => Effect.fail(failure) as Effect.Effect<A, CollectorFailure>,
+    })
+
+export const nativeCollect =
+    <M extends MessageCore>(owner: ClientOwner<M>) =>
+    <E = never, R = never>(channelId: string, options?: CollectorOptions<E, R, M>) =>
+        Effect.uninterruptible(
+            // Reading the handler when the Effect runs keeps a throwing getter an application fault in the Cause
+            readInput(() => options?.onMessage).pipe(
+                Effect.flatMap((onMessage) =>
+                    openNative(
+                        collect(owner, channelId, options, false, onMessage),
+                        (source) =>
+                            Effect.gen(function* () {
+                                const callerScope = yield* Effect.scope
+                                // A scoped waiter releases its registration when done, rather than retaining every completed collector until scope closure
+                                yield* releaseWhenClosed(source, callerScope)
+                                return nativeCollector(source)
+                            }),
+                        (failure): Collector<M> => failedNative<CollectorResult<M>>(failure),
+                    ),
+                ),
+            ),
+        )
+
+export const nativeCollectReactions =
+    <M extends MessageCore>(owner: ClientOwner<M>) =>
+    <E = never, R = never>(target: MessageReference, options?: ReactionCollectorOptions<E, R>) =>
+        Effect.uninterruptible(
+            // Reading the handler when the Effect runs keeps a throwing getter an application fault in the Cause
+            readInput(() => options?.onReaction).pipe(
+                Effect.flatMap((onReaction) =>
+                    openNative(
+                        collectReactions(owner, target, options, false, onReaction),
+                        (source) =>
+                            Effect.gen(function* () {
+                                const callerScope = yield* Effect.scope
+                                yield* releaseWhenClosed(source, callerScope)
+                                return nativeReactionCollector(source)
+                            }),
+                        (failure): ReactionCollector => failedNative<ReactionCollectorResult>(failure),
+                    ),
+                ),
+            ),
+        )
+
+export const nativeKeepTyping =
+    <M extends MessageCore>(owner: ClientOwner<M>) =>
+    <A, E, R>(channelId: string, task: Effect.Effect<A, E, R>, options?: MessageOperationOptions) =>
+        owner.keepTyping(channelId, task, options)

package/src/internal/binding/native.ts

@@ -0,0 +1,72 @@
+/**
+ * Native binder: Adapts each operation table entry to the Effect API.
+ * Invariant: Native operation members return the shared Effect unchanged, so they start nothing until the caller runs them and
+ * keep the caller's context, scope and interruption. Cache lookups read a closed client as absent and make misuse a defect,
+ * pure calculations return their value directly, and page entries become lazy Streams that release their traversal when
+ * consumption ends. Implements [SDK contracts: Public API model](/docs/SDK-CONTRACTS.md#public-api-model)
+ */
+import * as Effect from "effect/Effect"
+import type { MessageCore } from "#sdk/messages"
+import type { PaginationError } from "#sdk/pagination"
+import type { ClientOwner } from "#sdk/internal/client"
+import { paginationStream, type Pagination } from "#sdk/internal/pagination"
+import { isClientClosed, localValue } from "./execute.js"
+import { eachEntry, operationTable, type OperationTable } from "./operations.js"
+
+type Run<E> = E extends { readonly run: (owner: never, ...args: infer P) => infer R } ? [P, R] : never
+
+/** The native API member built from one table entry */
+export type NativeMember<E> = E extends { readonly kind: "op" | "lookup" }
+    ? Run<E> extends [infer P extends readonly unknown[], infer R]
+        ? (...args: P) => R
+        : never
+    : E extends { readonly kind: "get" }
+      ? Run<E> extends [infer P extends readonly unknown[], Effect.Effect<infer A, unknown>]
+          ? (...args: P) => Effect.Effect<A>
+          : never
+      : E extends { readonly kind: "pure" }
+        ? Run<E> extends [infer P extends readonly unknown[], Effect.Effect<infer A, unknown>]
+            ? (...args: P) => A
+            : never
+        : E extends { readonly kind: "page" }
+          ? Run<E> extends [
+                infer P extends readonly unknown[],
+                Effect.Effect<Pagination<infer A, infer F>, PaginationError>,
+            ]
+              ? (...args: P) => ReturnType<typeof paginationStream<A, F>>
+              : never
+          : E extends { readonly native: (owner: never) => infer N }
+            ? N
+            : never
+
+/** The native namespaces derived from the operation table */
+export type NativeNamespaces<T> = {
+    readonly [NS in keyof T]: { readonly [K in keyof T[NS]]: NativeMember<T[NS][K]> }
+}
+
+/** Build every native namespace object for one client from the operation table */
+export function bindNative<M extends MessageCore>(owner: ClientOwner<M>): NativeNamespaces<OperationTable<M>> {
+    const namespaces = eachEntry(operationTable<M>(), (entry, id) => {
+        switch (entry.kind) {
+            case "op":
+            case "lookup":
+                return (...args: readonly unknown[]) => entry.run(owner, ...args)
+            case "get":
+                // A closed client has no cache, and input misuse is a defect rather than a typed failure
+                return (...args: readonly unknown[]) =>
+                    entry.run(owner, ...args).pipe(
+                        Effect.catchIf(isClientClosed, () => Effect.succeed(undefined)),
+                        Effect.orDie,
+                    )
+            case "pure":
+                return (...args: readonly unknown[]) => localValue(entry.run(owner, ...args), id)
+            case "page":
+                return (...args: readonly unknown[]) => paginationStream(entry.run(owner, ...args))
+            case "stream":
+            case "custom":
+                return entry.native(owner)
+        }
+    })
+    // The table's derived member types are checked against the public interfaces by tests/types/binding-parity.ts
+    return namespaces as unknown as NativeNamespaces<OperationTable<M>>
+}