deepline 0.3.45 → 0.3.46

package/dist/bundling-sources/shared_libs/plays/core.ts

@@ -0,0 +1,466 @@
+import type { PlayDataset, PlayDatasetInput } from './dataset.js';
+import type { ToolExecuteResult } from './tool-result-types';
+import type {
+  DurableCallStaleAfterSeconds,
+  PlayAuthoringBindings,
+  PlayAuthoringColumnResolver,
+  PlayAuthoringConditionalStepResolver,
+  PlayAuthoringDatasetBuilder,
+  PlayAuthoringDatasetDefinitionOptions,
+  PlayAuthoringDatasetRowKey,
+  PlayAuthoringDatasetRunOptions,
+  PlayAuthoringDefineConfig,
+  PlayAuthoringDefinedPlay,
+  PlayAuthoringInputContract,
+  PlayAuthoringReferenceLike,
+  PlayAuthoringRuntimeContext,
+  PlayAuthoringStepOptions,
+  PlayAuthoringStepProgram,
+  PlayAuthoringStepProgramOutput,
+  PlayAuthoringStepProgramResolver,
+  PlayAuthoringStepProgramStep,
+  PlayAuthoringStepResolver,
+  PlayLooseObject,
+  PlayReturnObject as PlayAuthoringReturnObject,
+  PlaySecretAuth,
+  PlaySecretAuthInput,
+  PlaySecretAwareRequestInit,
+  PlaySecretHandle,
+  PlaySecretPromise,
+  PlaySecretValue,
+  PlaySqlQuery,
+  PlaySqlListenerDeclaration,
+  PlaySqlListenerEvent,
+  PlaySqlListenerFilterOperator,
+  PlaySqlListenerFilterScalar,
+  PlaySqlListenerOperation,
+  PlaySqlListenerWhere,
+  PlayToolExecutionRequest,
+} from './authoring-contract';
+import { createPlayInputContract } from './input-contract-definition';
+
+export type { ToolExecuteResult } from './tool-result-types';
+
+export type PlayBindings = PlayAuthoringBindings;
+export type SqlListenerOperation = PlaySqlListenerOperation;
+export type SqlListenerFilterScalar = PlaySqlListenerFilterScalar;
+export type SqlListenerFilterOperator = PlaySqlListenerFilterOperator;
+export type SqlListenerWhere = PlaySqlListenerWhere;
+export type SqlListenerDeclaration = PlaySqlListenerDeclaration;
+
+export type SqlListenerEvent<T extends object = Record<string, unknown>> =
+  PlaySqlListenerEvent<T>;
+
+/** @deprecated Pass a SQL string directly to ctx.customerDb.query. */
+export type SqlQuery = PlaySqlQuery;
+export type SecretHandle = PlaySecretHandle;
+export type SecretPromise = PlaySecretPromise;
+export type SecretValue = PlaySecretValue;
+export type SecretAuth = PlaySecretAuth;
+export type SecretAuthInput = PlaySecretAuthInput;
+export type SecretAwareRequestInit = PlaySecretAwareRequestInit;
+export type LoosePlayObject = PlayLooseObject;
+
+export type ToolExecutionRequest = PlayToolExecutionRequest;
+
+export type StepResolver<Row, Value> = PlayAuthoringStepResolver<
+  Row,
+  Value,
+  DeeplinePlayRuntimeContext
+>;
+
+export type ConditionalStepResolver<
+  Row,
+  Value,
+  Else = null,
+> = PlayAuthoringConditionalStepResolver<
+  Row,
+  Value,
+  DeeplinePlayRuntimeContext,
+  Else
+>;
+
+export type StepOptions<Row, Value = unknown> = PlayAuthoringStepOptions<
+  Row,
+  Value
+>;
+
+export type StepProgram<
+  Input,
+  Output,
+  Return = Output,
+> = PlayAuthoringStepProgram<Input, Output, DeeplinePlayRuntimeContext, Return>;
+
+export type StepProgramResolver<Input, Return> =
+  PlayAuthoringStepProgramResolver<Input, Return, DeeplinePlayRuntimeContext>;
+
+export type PlayStepProgramStep =
+  PlayAuthoringStepProgramStep<DeeplinePlayRuntimeContext>;
+
+export type ColumnResolver<Row, Value> = PlayAuthoringColumnResolver<
+  Row,
+  Value,
+  DeeplinePlayRuntimeContext
+>;
+
+export type StepProgramOutput<TProgram> =
+  PlayAuthoringStepProgramOutput<TProgram>;
+
+export type DatasetRowKey<InputRow extends object> =
+  PlayAuthoringDatasetRowKey<InputRow>;
+
+export type DatasetDefinitionOptions<InputRow extends object> =
+  PlayAuthoringDatasetDefinitionOptions<InputRow>;
+
+export type DatasetRunOptions<InputRow extends object> =
+  PlayAuthoringDatasetRunOptions<InputRow>;
+
+export type DatasetBuilder<
+  InputRow extends object,
+  OutputRow extends object,
+> = PlayAuthoringDatasetBuilder<
+  InputRow,
+  OutputRow,
+  DeeplinePlayRuntimeContext
+>;
+
+export type PlayReferenceLike = PlayAuthoringReferenceLike;
+
+export type DeeplinePlayRuntimeContext = PlayAuthoringRuntimeContext;
+
+export type PlayReturnObject = PlayAuthoringReturnObject;
+export type PlayInputContract<TInput> = PlayAuthoringInputContract<TInput>;
+export type DefinePlayConfig<
+  TInput,
+  TOutput extends PlayReturnObject,
+> = PlayAuthoringDefineConfig<TInput, TOutput, DeeplinePlayRuntimeContext>;
+
+export type PlayMetadata = {
+  name: string;
+  description?: string;
+  bindings?: PlayBindings;
+  inputSchema?: Record<string, unknown>;
+  billing?: PlayBindings['billing'];
+  runtime?: PlayBindings['runtime'];
+  compatibility?: PlayBindings['compatibility'];
+};
+
+export type CoreNamedPlayHandle<
+  TInput = Record<string, unknown>,
+  TOutput = unknown,
+> = {
+  readonly name: string;
+  get(): Promise<unknown>;
+  runs(): Promise<unknown>;
+  versions(): Promise<unknown>;
+  publish(options?: { revisionId?: string }): Promise<unknown>;
+  clearHistory(options?: { tableNamespaces?: string[] }): Promise<unknown>;
+  run(input: TInput, options?: { revisionId?: string }): Promise<unknown>;
+  runSync(input: TInput, options?: { revisionId?: string }): Promise<TOutput>;
+};
+
+export type DefinedPlay<
+  TInput,
+  TOutput extends PlayReturnObject,
+  THandle extends object = CoreNamedPlayHandle<TInput, TOutput>,
+> = PlayAuthoringDefinedPlay<
+  TInput,
+  TOutput,
+  DeeplinePlayRuntimeContext,
+  THandle
+>;
+
+export const PLAY_METADATA_SYMBOL = Symbol.for('deepline.play.metadata');
+
+class PlayCoreConditionalStepResolver<
+  Row,
+  Value,
+  ElseValue,
+> implements ConditionalStepResolver<Row, Value, ElseValue> {
+  readonly kind = 'conditional' as const;
+
+  constructor(
+    readonly when: (row: Row, index: number) => boolean | Promise<boolean>,
+    readonly run: StepResolver<Row, Value>,
+    readonly elseValue: ElseValue,
+  ) {}
+
+  else<ValueElse>(
+    value: ValueElse,
+  ): ConditionalStepResolver<Row, Value, ValueElse> {
+    return new PlayCoreConditionalStepResolver(this.when, this.run, value);
+  }
+}
+
+class PlayCoreStepProgram<Input, Output, ReturnValue> implements StepProgram<
+  Input,
+  Output,
+  ReturnValue
+> {
+  readonly kind = 'steps' as const;
+  declare readonly __inputType?: (input: Input) => void;
+
+  constructor(
+    readonly steps: readonly PlayStepProgramStep[],
+    readonly returnResolver?: StepResolver<Output, ReturnValue>,
+  ) {}
+
+  step<Name extends string, Value>(
+    name: Name,
+    resolver:
+      | StepResolver<Output, Value>
+      | ConditionalStepResolver<Output, Value>
+      | StepProgramResolver<Output, Value>,
+  ): StepProgram<Input, Output & Record<Name, Value>, ReturnValue>;
+  step<Name extends string, Value>(
+    name: Name,
+    resolver: StepResolver<Output, Value> | StepProgramResolver<Output, Value>,
+    options: StepOptions<Output>,
+  ): StepProgram<Input, Output & Record<Name, Value | null>, ReturnValue>;
+  step<Name extends string, Value>(
+    name: Name,
+    resolver:
+      | StepResolver<Output, Value>
+      | ConditionalStepResolver<Output, Value>
+      | StepProgramResolver<Output, Value>,
+    options?: StepOptions<Output>,
+  ): StepProgram<Input, Output & Record<Name, Value | null>, ReturnValue> {
+    if (!name.trim()) {
+      throw new Error(
+        'steps().step(name, ...) requires a non-empty step name.',
+      );
+    }
+    const stepResolver =
+      options?.runIf && !isConditionalStepResolver(resolver)
+        ? new PlayCoreConditionalStepResolver(
+            options.runIf,
+            resolver as StepResolver<Output, Value>,
+            null,
+          )
+        : resolver;
+    return new PlayCoreStepProgram(
+      [
+        ...this.steps,
+        {
+          name,
+          ...(options?.recompute === true ? { recompute: true } : {}),
+          ...(options?.recomputeOnError === true
+            ? { recomputeOnError: true }
+            : {}),
+          ...(typeof options?.staleAfterSeconds === 'number'
+            ? { staleAfterSeconds: options.staleAfterSeconds }
+            : {}),
+          resolver: stepResolver as PlayStepProgramStep['resolver'],
+        },
+      ],
+      this.returnResolver as StepResolver<
+        Output & Record<Name, Value | null>,
+        ReturnValue
+      >,
+    );
+  }
+
+  return<Value>(
+    resolver: StepResolver<Output, Value>,
+  ): StepProgram<Input, Output, Value> {
+    return new PlayCoreStepProgram(this.steps, resolver);
+  }
+}
+
+function isConditionalStepResolver(
+  value: unknown,
+): value is ConditionalStepResolver<unknown, unknown> {
+  return (
+    value !== null &&
+    typeof value === 'object' &&
+    (value as { kind?: unknown }).kind === 'conditional'
+  );
+}
+
+export function steps<TInput>(): StepProgram<TInput, TInput, TInput> {
+  return new PlayCoreStepProgram<TInput, TInput, TInput>([]);
+}
+
+export function defineInput<TInput>(
+  schema: Record<string, unknown>,
+): PlayInputContract<TInput> {
+  return createPlayInputContract<TInput>(schema);
+}
+
+export function createUnavailableNamedPlayHandle<
+  TInput,
+  TOutput extends PlayReturnObject,
+>(name: string): CoreNamedPlayHandle<TInput, TOutput> {
+  const unavailable = () => {
+    throw new Error(
+      `definePlay("${name}") remote lifecycle methods are unavailable inside play execution. Use ctx.runPlay(...) for runtime composition.`,
+    );
+  };
+  return {
+    name,
+    get: unavailable,
+    runs: unavailable,
+    versions: unavailable,
+    publish: unavailable,
+    clearHistory: unavailable,
+    run: unavailable,
+    runSync: unavailable,
+  };
+}
+
+export function createDefinedPlay<
+  TInput,
+  TOutput extends PlayReturnObject,
+  THandle extends object,
+>(
+  nameOrConfig: string | DefinePlayConfig<TInput, TOutput>,
+  maybeFn:
+    | ((ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>)
+    | undefined,
+  maybeBindings: PlayBindings | undefined,
+  createHandle: (name: string) => THandle,
+): DefinedPlay<TInput, TOutput, THandle> {
+  const config =
+    typeof nameOrConfig === 'string'
+      ? {
+          name: nameOrConfig,
+          fn: maybeFn,
+          bindings: maybeBindings,
+          description: maybeBindings?.description,
+          inputSchema: undefined,
+          billing: maybeBindings?.billing,
+          runtime: maybeBindings?.runtime,
+          compatibility: maybeBindings?.compatibility,
+        }
+      : {
+          name: nameOrConfig.id,
+          fn: nameOrConfig.run,
+          bindings: nameOrConfig.bindings,
+          description: nameOrConfig.description,
+          inputSchema: nameOrConfig.input.schema,
+          billing: nameOrConfig.billing,
+          runtime: nameOrConfig.runtime ?? nameOrConfig.bindings?.runtime,
+          compatibility:
+            nameOrConfig.compatibility ?? nameOrConfig.bindings?.compatibility,
+        };
+
+  const name = config.name;
+  const fn = config.fn;
+  const description = config.description?.trim();
+  if (typeof fn !== 'function') {
+    throw new Error('definePlay(...) requires an async run function.');
+  }
+  if (name.includes('/')) {
+    throw new Error('Play name cannot contain "/". Slash is reserved.');
+  }
+  const normalizedName = name
+    .trim()
+    .replace(/[^a-z0-9]+/gi, '_')
+    .replace(/_+/g, '_')
+    .replace(/^_+|_+$/g, '')
+    .toLowerCase();
+  if (!normalizedName) {
+    throw new Error('Play name must contain a letter or number.');
+  }
+  if (normalizedName.length > 63) {
+    throw new Error(
+      `Play name too long after normalization (${normalizedName.length}/63): "${normalizedName}".`,
+    );
+  }
+
+  const metadata: PlayMetadata = {
+    name,
+    ...(description ? { description } : {}),
+    ...(config.bindings ? { bindings: config.bindings } : {}),
+    ...(config.inputSchema ? { inputSchema: config.inputSchema } : {}),
+    ...(config.billing ? { billing: config.billing } : {}),
+    ...(config.runtime ? { runtime: config.runtime } : {}),
+    ...(config.compatibility ? { compatibility: config.compatibility } : {}),
+  };
+  const play = fn as DefinedPlay<TInput, TOutput, THandle>;
+
+  Object.defineProperty(play, PLAY_METADATA_SYMBOL, {
+    value: metadata,
+    enumerable: false,
+    configurable: false,
+    writable: false,
+  });
+  Object.defineProperty(play, 'playName', {
+    value: name,
+    enumerable: true,
+    configurable: false,
+    writable: false,
+  });
+  Object.defineProperty(play, 'bindings', {
+    value: config.bindings,
+    enumerable: true,
+    configurable: false,
+    writable: false,
+  });
+  Object.defineProperty(play, 'runtime', {
+    value: config.runtime,
+    enumerable: true,
+    configurable: false,
+    writable: false,
+  });
+  Object.defineProperty(play, 'compatibility', {
+    value: config.compatibility,
+    enumerable: true,
+    configurable: false,
+    writable: false,
+  });
+
+  const handle = createHandle(name) as Record<PropertyKey, unknown>;
+  for (const key of Reflect.ownKeys(handle)) {
+    Object.defineProperty(play, key, {
+      value: handle[key],
+      enumerable: false,
+      configurable: false,
+      writable: false,
+    });
+  }
+
+  return play;
+}
+
+export function definePlay<TInput, TOutput extends PlayReturnObject>(
+  config: DefinePlayConfig<TInput, TOutput>,
+): DefinedPlay<TInput, TOutput>;
+export function definePlay<TInput, TOutput extends PlayReturnObject>(
+  name: string,
+  fn: (ctx: DeeplinePlayRuntimeContext, input: TInput) => Promise<TOutput>,
+  bindings?: PlayBindings,
+): DefinedPlay<TInput, TOutput>;
+export function definePlay<TInput, TOutput extends PlayReturnObject>(
+  nameOrConfig: string | DefinePlayConfig<TInput, TOutput>,
+  maybeFn?: (
+    ctx: DeeplinePlayRuntimeContext,
+    input: TInput,
+  ) => Promise<TOutput>,
+  maybeBindings?: PlayBindings,
+): DefinedPlay<TInput, TOutput> {
+  return createDefinedPlay(nameOrConfig, maybeFn, maybeBindings, (name) =>
+    createUnavailableNamedPlayHandle<TInput, TOutput>(name),
+  );
+}
+
+export const defineWorkflow = definePlay;
+
+export function getDefinedPlayMetadata(value: unknown): PlayMetadata | null {
+  if (typeof value !== 'function') {
+    return null;
+  }
+  const metadata = (value as unknown as Record<PropertyKey, unknown>)[
+    PLAY_METADATA_SYMBOL
+  ];
+  if (!metadata || typeof metadata !== 'object') {
+    return null;
+  }
+  const candidate = metadata as PlayMetadata;
+  if (!candidate.name || typeof candidate.name !== 'string') {
+    return null;
+  }
+  return candidate;
+}
+
+export type { PlayDataset, PlayDatasetInput };