@yolk-sdk/extractors 0.1.0-canary.98

package/src/node/extraction-isolation.ts

@@ -0,0 +1,289 @@
+import { Worker } from 'node:worker_threads'
+import { Effect, Match, Option } from 'effect'
+import * as Schema from 'effect/Schema'
+import { FileExtractionError } from '../errors.ts'
+import type { FileExtractionFailureReason, FileExtractorError } from '../errors.ts'
+import type { ExtractedFile, FileInput } from '../format.ts'
+import type { FileExtractorLimits } from '../limits.ts'
+import type { ParsedFileFormat } from './extract-file.ts'
+import { decodeWorkerMessage, revivedError } from './extraction-worker-protocol.ts'
+import type { ExtractionWorkerRequest } from './extraction-worker-protocol.ts'
+import { makeSlotPool, processSlotPool, processWorkerLimit, withSlot } from './worker-admission.ts'
+
+/** Limits for the worker each PDF, DOCX, XLSX, or PPTX extraction runs in. */
+export type WorkerIsolationOptions = {
+  /** V8 old-generation heap of the worker, in MB. Default 256. */
+  readonly maxOldGenerationSizeMb?: number
+  /** V8 young-generation heap of the worker, in MB. Default 32. */
+  readonly maxYoungGenerationSizeMb?: number
+  /** Stack of the worker's main thread, in MB. Default 4 (Node's own default). */
+  readonly stackSizeMb?: number
+  /**
+   * Wall-clock time a worker may run before it is terminated, in ms. Default 30,000. At most
+   * 2³¹−1 (Node's largest timer delay).
+   */
+  readonly timeoutMs?: number
+  /**
+   * This layer's share of the realm-wide worker pool: at most this many of its extractions run at
+   * once. Every layer in a JavaScript realm (the main thread, or each worker thread that builds
+   * the layer) shares one pool of 4 workers, however often the layer is built, so this can only
+   * lower the layer's share. 1 to 4; default 4.
+   */
+  readonly maxConcurrentWorkers?: number
+  /**
+   * How long an extraction may wait for a worker slot, in ms, before it fails with
+   * `reason: 'busy'` without starting a worker. Slots are handed out first come, first served, and
+   * a slot freed after the deadline never admits the extraction. Default: the layer's `timeoutMs`.
+   * At most 2³¹−1 (Node's largest timer delay).
+   */
+  readonly maxQueueWaitMs?: number
+  /**
+   * The worker entry. Default: the package's self-contained `dist/node/extraction-worker.mjs`,
+   * found from this module's own location (in `dist`, or in `src` when a workspace or a bundler
+   * that keeps module locations, such as Next.js Turbopack, runs the source). When this module has
+   * been bundled into a file of another name, there is no default and extraction fails with
+   * `reason: 'worker-unavailable'` without starting a worker; point this at a copy of
+   * `@yolk-sdk/extractors/node/extraction-worker` instead.
+   */
+  readonly workerUrl?: string | URL
+}
+
+/**
+ * Where parsers run. `'worker'` (the default) and an options object run each PDF, DOCX, XLSX, and
+ * PPTX extraction in a fresh `worker_threads` worker with V8 heap, stack, and time limits.
+ * `'none'` runs parsers in the calling thread: only for environments without worker threads, and
+ * unsafe for untrusted input (a crafted file can exhaust the process heap or block the event loop).
+ */
+export type FileExtractorIsolation = 'worker' | 'none' | WorkerIsolationOptions
+
+const PositiveSafeInteger = Schema.Int.pipe(
+  Schema.check(Schema.isGreaterThan(0)),
+  Schema.check(Schema.isLessThanOrEqualTo(Number.MAX_SAFE_INTEGER))
+)
+
+/** Node's largest `setTimeout` delay; a larger one fires after 1 ms instead. */
+const MaxTimerMs = PositiveSafeInteger.pipe(Schema.check(Schema.isLessThanOrEqualTo(2_147_483_647)))
+
+/** Resolved worker settings; every value is a positive integer, and timers fit `setTimeout`. */
+export const WorkerIsolationSettings = Schema.Struct({
+  maxOldGenerationSizeMb: PositiveSafeInteger,
+  maxYoungGenerationSizeMb: PositiveSafeInteger,
+  stackSizeMb: PositiveSafeInteger,
+  timeoutMs: MaxTimerMs,
+  maxConcurrentWorkers: PositiveSafeInteger.pipe(
+    Schema.check(Schema.isLessThanOrEqualTo(processWorkerLimit))
+  ),
+  maxQueueWaitMs: MaxTimerMs
+})
+
+export type WorkerIsolationSettings = typeof WorkerIsolationSettings.Type
+
+/**
+ * Defaults. 256 MB of old generation holds SheetJS's cell objects for the default limits (100,000
+ * visited cells, 50 MiB expanded) several times over and PDF.js's working set for ordinary PDFs,
+ * and the realm-wide pool of four workers keeps their V8 heaps near 1 GB together. That bounds
+ * heap, not the process: Buffers and PDF.js's decoded data live outside it (see the README).
+ * 32 MB of young generation is twice V8's usual 64-bit default, enough for short-lived parser
+ * strings. 30 s is far above legitimate parse times at the default limits (well under a second
+ * for the research workbooks) and below common serverless request budgets; a queued extraction
+ * waits at most as long again for a slot.
+ */
+export const defaultWorkerIsolation: WorkerIsolationSettings = {
+  maxOldGenerationSizeMb: 256,
+  maxYoungGenerationSizeMb: 32,
+  stackSizeMb: 4,
+  timeoutMs: 30_000,
+  maxConcurrentWorkers: processWorkerLimit,
+  maxQueueWaitMs: 30_000
+}
+
+const isolationModule =
+  /\/(?:src\/node\/extraction-isolation\.ts|dist\/node\/extraction-isolation\.mjs)$/
+
+/**
+ * The built worker for an isolation module at `moduleUrl`: `dist/node/extraction-worker.mjs` of
+ * the same package, from `dist/node/extraction-isolation.mjs` (installed) or
+ * `src/node/extraction-isolation.ts` (workspace source, which must be built first). Any other
+ * location (this module bundled into a chunk) has no default: `undefined`, and nothing is started.
+ * The URL is derived from the module URL at runtime, never written as
+ * `new URL('./…', import.meta.url)`: bundlers rewrite that pattern into a copied asset.
+ */
+export const extractionWorkerUrlFor = (moduleUrl: string): URL | undefined =>
+  isolationModule.test(moduleUrl)
+    ? new URL(moduleUrl.replace(isolationModule, '/dist/node/extraction-worker.mjs'))
+    : undefined
+
+/** The default worker entry for this module; see `extractionWorkerUrlFor`. */
+export const defaultExtractionWorkerUrl = () => extractionWorkerUrlFor(import.meta.url)
+
+const stoppedMessages: Readonly<Record<FileExtractionFailureReason, string>> = {
+  'resource-limit': 'File extraction exceeded its memory limit.',
+  timeout: 'File extraction timed out.',
+  'worker-unavailable': 'File extraction worker could not start.',
+  'worker-failed': 'File extraction worker failed.',
+  busy: 'File extraction is busy. Try again later.'
+}
+
+const stopped = (format: ParsedFileFormat, reason: FileExtractionFailureReason, cause?: unknown) =>
+  cause === undefined
+    ? new FileExtractionError({ format, reason, message: stoppedMessages[reason] })
+    : new FileExtractionError({ format, reason, message: stoppedMessages[reason], cause })
+
+const isOutOfMemory = (error: unknown) =>
+  error instanceof Error && 'code' in error && error.code === 'ERR_WORKER_OUT_OF_MEMORY'
+
+type WorkerOutcome = Effect.Effect<ExtractedFile, FileExtractorError>
+
+type StartedWorker = {
+  readonly worker: Worker
+  /** Settles once with the worker's result or failure; listeners are attached at construction. */
+  readonly outcome: Promise<WorkerOutcome>
+}
+
+/**
+ * Start a worker and attach its listeners in the same tick, so no `error` event can go unheard
+ * (an unheard worker `error` would throw in the host process).
+ */
+const startWorker = (
+  workerUrl: string | URL,
+  options: ConstructorParameters<typeof Worker>[1],
+  format: ParsedFileFormat
+): StartedWorker => {
+  const worker = new Worker(workerUrl, options)
+
+  const outcome = new Promise<WorkerOutcome>(resolve => {
+    let started = false
+
+    worker.on('message', (raw: unknown) =>
+      Option.match(decodeWorkerMessage(raw), {
+        onNone: () => resolve(Effect.fail(stopped(format, 'worker-failed'))),
+        onSome: message =>
+          Match.valueTags(message, {
+            WorkerStarted: () => {
+              started = true
+            },
+            WorkerSucceeded: ({ file }) => resolve(Effect.succeed(file)),
+            WorkerFailed: ({ error }) => resolve(Effect.fail(revivedError(error))),
+            WorkerDefect: ({ message: defect }) =>
+              resolve(Effect.die(new Error(`File extraction worker defect: ${defect}`)))
+          })
+      })
+    )
+
+    // `ERR_WORKER_OUT_OF_MEMORY` when a heap limit is hit; errors before `WorkerStarted` mean the
+    // worker file or its imports could not load.
+    worker.on('error', (error: unknown) => {
+      const reason = started ? 'worker-failed' : 'worker-unavailable'
+
+      resolve(Effect.fail(stopped(format, isOutOfMemory(error) ? 'resource-limit' : reason, error)))
+    })
+
+    worker.on('exit', (code: number) =>
+      resolve(
+        Effect.fail(
+          stopped(
+            format,
+            started ? 'worker-failed' : 'worker-unavailable',
+            new Error(`Worker exited with code ${code}`)
+          )
+        )
+      )
+    )
+  })
+
+  return { worker, outcome }
+}
+
+/**
+ * Wait for the worker's outcome, at most `timeoutMs` of wall-clock time (a real timer, not the
+ * Effect `Clock`, so a test clock cannot stall it). The caller's scope terminates the worker
+ * whatever happens, including interruption.
+ */
+const awaitOutcome = ({ outcome }: StartedWorker, format: ParsedFileFormat, timeoutMs: number) =>
+  Effect.callback<ExtractedFile, FileExtractorError>(resume => {
+    const timer = setTimeout(() => resume(Effect.fail(stopped(format, 'timeout'))), timeoutMs)
+
+    void outcome.then(result => {
+      clearTimeout(timer)
+      resume(result)
+    })
+
+    return Effect.sync(() => clearTimeout(timer))
+  })
+
+export type WorkerExtractor = (
+  input: FileInput,
+  format: ParsedFileFormat,
+  limits: FileExtractorLimits
+) => Effect.Effect<ExtractedFile, FileExtractorError>
+
+const missingWorker = new Error(
+  'No default extraction worker next to this module; set isolation.workerUrl'
+)
+
+/**
+ * Run each extraction in a fresh worker: the input is copied into a transferred buffer, the
+ * worker returns only text and metadata, and the worker is terminated when the result arrives,
+ * the timeout fires, or the caller is interrupted. Admission goes through this layer's share and
+ * the realm-wide pool (`worker-admission.ts`); a slot is freed only once its worker has
+ * terminated. A worker that cannot start, or a missing `workerUrl`, fails closed with
+ * `reason: 'worker-unavailable'`; there is no in-process fallback.
+ */
+export const makeWorkerExtractor = (
+  settings: WorkerIsolationSettings,
+  workerUrl: string | URL | undefined
+): Effect.Effect<WorkerExtractor> =>
+  Effect.sync(() => {
+    const layerPool = makeSlotPool(settings.maxConcurrentWorkers)
+
+    return (input, format, limits) => {
+      if (workerUrl === undefined)
+        return Effect.fail(stopped(format, 'worker-unavailable', missingWorker))
+
+      const extraction = Effect.gen(function* () {
+        const bytes = new Uint8Array(input.bytes)
+
+        const request: ExtractionWorkerRequest = {
+          filename: input.filename,
+          mediaType: input.mediaType,
+          bytes,
+          format,
+          limits
+        }
+
+        const started = yield* Effect.acquireRelease(
+          Effect.try({
+            try: () =>
+              startWorker(
+                workerUrl,
+                {
+                  workerData: request,
+                  transferList: [bytes.buffer],
+                  resourceLimits: {
+                    maxOldGenerationSizeMb: settings.maxOldGenerationSizeMb,
+                    maxYoungGenerationSizeMb: settings.maxYoungGenerationSizeMb,
+                    stackSizeMb: settings.stackSizeMb
+                  }
+                },
+                format
+              ),
+            catch: cause => stopped(format, 'worker-unavailable', cause)
+          }),
+          ({ worker }) => Effect.promise(() => worker.terminate())
+        )
+
+        return yield* awaitOutcome(started, format, settings.timeoutMs)
+      })
+
+      return Effect.suspend(() => {
+        // One deadline for both waits, from when the extraction asks for a worker.
+        const deadline = Date.now() + settings.maxQueueWaitMs
+        const busy = () => stopped(format, 'busy')
+
+        return Effect.scoped(extraction).pipe(
+          withSlot(processSlotPool(), deadline, busy),
+          withSlot(layerPool, deadline, busy)
+        )
+      })
+    }
+  })

package/src/node/extraction-worker-protocol.ts

@@ -0,0 +1,130 @@
+import { Match, Option } from 'effect'
+import * as Schema from 'effect/Schema'
+import { FileExtractionError, OfficeArchiveError, SheetJsUnavailableError } from '../errors.ts'
+import type { FileExtractorError } from '../errors.ts'
+import { extractedFileFormats } from '../format.ts'
+import { FileExtractorLimits } from '../limits.ts'
+
+/**
+ * Messages between the Node layer and `extraction-worker.ts`. Both sides encode and decode with
+ * these schemas; only plain data crosses the thread boundary (no parser objects).
+ */
+
+export const ParsedFileFormat = Schema.Literals(['pdf', 'docx', 'pptx', 'xlsx'])
+
+/** `workerData`: the input bytes arrive in a transferred buffer. */
+export const ExtractionWorkerRequest = Schema.Struct({
+  filename: Schema.String,
+  mediaType: Schema.String,
+  bytes: Schema.Uint8Array,
+  format: ParsedFileFormat,
+  limits: FileExtractorLimits
+})
+
+export type ExtractionWorkerRequest = typeof ExtractionWorkerRequest.Type
+
+const ExtractedFileMessage = Schema.Struct({
+  content: Schema.String,
+  metadata: Schema.Struct({
+    format: Schema.Literals(extractedFileFormats),
+    title: Schema.optional(Schema.String),
+    pageCount: Schema.optional(Schema.Number),
+    sheetNames: Schema.optional(Schema.Array(Schema.String))
+  })
+})
+
+/** Posted once the worker's modules have loaded. */
+export class WorkerStarted extends Schema.TaggedClass<WorkerStarted>()('WorkerStarted', {}) {}
+
+export class WorkerSucceeded extends Schema.TaggedClass<WorkerSucceeded>()('WorkerSucceeded', {
+  file: ExtractedFileMessage
+}) {}
+
+export class WorkerFailed extends Schema.TaggedClass<WorkerFailed>()('WorkerFailed', {
+  error: Schema.Union([FileExtractionError, SheetJsUnavailableError])
+}) {}
+
+/** An unexpected defect inside the worker (a bug, not a property of the file). */
+export class WorkerDefect extends Schema.TaggedClass<WorkerDefect>()('WorkerDefect', {
+  message: Schema.String
+}) {}
+
+export const ExtractionWorkerMessage = Schema.Union([
+  WorkerStarted,
+  WorkerSucceeded,
+  WorkerFailed,
+  WorkerDefect
+])
+
+export const decodeWorkerMessage = Schema.decodeUnknownOption(ExtractionWorkerMessage)
+
+/** A cause as it crosses the thread boundary: its name, message, and archive size, if any. */
+const PortableCause = Schema.Struct({
+  name: Schema.String,
+  message: Schema.String,
+  expandedBytes: Schema.optional(Schema.Number)
+})
+
+const archiveErrorName = 'OfficeArchiveError'
+
+const portableCause = (cause: unknown): typeof PortableCause.Type | undefined => {
+  if (cause instanceof OfficeArchiveError)
+    return { name: archiveErrorName, message: cause.message, expandedBytes: cause.expandedBytes }
+
+  return cause instanceof Error ? { name: cause.name, message: cause.message } : undefined
+}
+
+/** The worker's reply for a failed extraction. */
+export const failureMessage = (error: FileExtractorError): WorkerFailed | WorkerDefect =>
+  Match.valueTags(error, {
+    FileExtractionError: failure =>
+      WorkerFailed.make({
+        error: new FileExtractionError({
+          message: failure.message,
+          format: failure.format,
+          reason: failure.reason,
+          cause: portableCause(failure.cause)
+        })
+      }),
+    SheetJsUnavailableError: failure =>
+      WorkerFailed.make({
+        error: new SheetJsUnavailableError({
+          reason: failure.reason,
+          installedVersion: failure.installedVersion,
+          cause: portableCause(failure.cause)
+        })
+      }),
+    UnsupportedFileFormatError: () =>
+      WorkerDefect.make({ message: 'The worker received an unsupported format' })
+  })
+
+/** Turn a portable archive cause back into an `OfficeArchiveError`; other causes stay as sent. */
+const revivedCause = (cause: unknown) =>
+  Option.match(Schema.decodeUnknownOption(PortableCause)(cause), {
+    onNone: () => cause,
+    onSome: portable =>
+      portable.name === archiveErrorName
+        ? new OfficeArchiveError({
+            message: portable.message,
+            expandedBytes: portable.expandedBytes
+          })
+        : portable
+  })
+
+/** The error a worker reported, with its archive cause revived. */
+export const revivedError = (error: WorkerFailed['error']) =>
+  Match.valueTags(error, {
+    FileExtractionError: failure =>
+      new FileExtractionError({
+        message: failure.message,
+        format: failure.format,
+        reason: failure.reason,
+        cause: revivedCause(failure.cause)
+      }),
+    SheetJsUnavailableError: failure =>
+      new SheetJsUnavailableError({
+        reason: failure.reason,
+        installedVersion: failure.installedVersion,
+        cause: revivedCause(failure.cause)
+      })
+  })

package/src/node/extraction-worker.ts

@@ -0,0 +1,56 @@
+// Worker entry for isolated extraction (`@yolk-sdk/extractors/node/extraction-worker`). The Node
+// layer starts it once per extraction with V8 resource limits; it reads the request from
+// `workerData`, runs the parsers, posts one plain-data result, and exits. Importing it outside a
+// worker thread does nothing. The build bundles it into one self-contained
+// `dist/node/extraction-worker.mjs` (effect, fflate, mammoth, unpdf, and this package inlined);
+// only the optional `xlsx` peer stays a dynamic import.
+import { parentPort, workerData } from 'node:worker_threads'
+import { Cause, Effect, Exit, Option } from 'effect'
+import * as Schema from 'effect/Schema'
+import { extractParsedFile } from './extract-file.ts'
+import {
+  ExtractionWorkerMessage,
+  ExtractionWorkerRequest,
+  failureMessage,
+  WorkerDefect,
+  WorkerStarted,
+  WorkerSucceeded
+} from './extraction-worker-protocol.ts'
+import { defaultSheetJsLoader } from './sheetjs.ts'
+
+const run = (port: NonNullable<typeof parentPort>) =>
+  Effect.gen(function* () {
+    const post = (message: typeof ExtractionWorkerMessage.Type) =>
+      Schema.encodeEffect(ExtractionWorkerMessage)(message).pipe(
+        Effect.orDie,
+        Effect.map(encoded => port.postMessage(encoded))
+      )
+
+    yield* post(WorkerStarted.make({}))
+
+    const exit = yield* Effect.exit(
+      Schema.decodeUnknownEffect(ExtractionWorkerRequest)(workerData).pipe(
+        Effect.orDie,
+        Effect.flatMap(request =>
+          extractParsedFile(
+            { filename: request.filename, mediaType: request.mediaType, bytes: request.bytes },
+            request.format,
+            request.limits,
+            // The worker always loads the installed SheetJS itself, with the version check.
+            defaultSheetJsLoader
+          )
+        )
+      )
+    )
+
+    if (Exit.isSuccess(exit)) return yield* post(WorkerSucceeded.make({ file: exit.value }))
+
+    return yield* post(
+      Option.match(Cause.findErrorOption(exit.cause), {
+        onSome: failureMessage,
+        onNone: () => WorkerDefect.make({ message: Cause.pretty(exit.cause) })
+      })
+    )
+  })
+
+if (parentPort !== null) await Effect.runPromise(run(parentPort))

package/src/node/index.ts

@@ -0,0 +1,21 @@
+// Node-only implementation: PDF (unpdf), DOCX (mammoth), XLSX (SheetJS, an optional peer loaded
+// lazily), PPTX (fflate), and bounded Office archive validation on node:zlib/node:stream. Parsers
+// run in a `worker_threads` worker (`./extraction-worker`) unless `isolation: 'none'`.
+
+export { FileExtractorLayer, makeFileExtractorLayer } from './live-layer.ts'
+
+export type { FileExtractorOptions } from './live-layer.ts'
+
+export { defaultWorkerIsolation } from './extraction-isolation.ts'
+
+export type { FileExtractorIsolation, WorkerIsolationOptions } from './extraction-isolation.ts'
+
+export { normalizeOfficeArchive } from './office-archive.ts'
+
+export type { OfficeArchiveLimits } from './office-archive.ts'
+
+export type { SheetJsLoader } from './sheetjs.ts'
+
+export { FileExtractor } from '../service.ts'
+
+export type { FileExtractorApi } from '../service.ts'

package/src/node/live-layer.ts

@@ -0,0 +1,136 @@
+import { Effect, Layer } from 'effect'
+import * as Schema from 'effect/Schema'
+import { FileExtractionError, UnsupportedFileFormatError } from '../errors.ts'
+import { fileFormatFor } from '../format.ts'
+import { defaultFileExtractorLimits, FileExtractorLimits } from '../limits.ts'
+import { FileExtractor } from '../service.ts'
+import type { FileExtractorApi } from '../service.ts'
+import { extractParsedFile, isParsedFileFormat, makeExtractedFile } from './extract-file.ts'
+import type { ParsedFileFormat } from './extract-file.ts'
+import {
+  defaultExtractionWorkerUrl,
+  defaultWorkerIsolation,
+  makeWorkerExtractor,
+  WorkerIsolationSettings
+} from './extraction-isolation.ts'
+import type { FileExtractorIsolation, WorkerExtractor } from './extraction-isolation.ts'
+import { defaultSheetJsLoader } from './sheetjs.ts'
+import type { SheetJsLoader } from './sheetjs.ts'
+
+export type FileExtractorOptions = {
+  /** Override any default limit; see `defaultFileExtractorLimits`. */
+  readonly limits?: Partial<FileExtractorLimits>
+  /**
+   * Where parsers run (default `'worker'`): each PDF, DOCX, XLSX, and PPTX extraction runs in a
+   * fresh worker thread with V8 heap, stack, and time limits, admitted through a pool of 4 workers
+   * per JavaScript realm; pass an object to change them. `'none'` parses in the calling thread and is
+   * unsafe for untrusted input.
+   */
+  readonly isolation?: FileExtractorIsolation
+  /**
+   * Load SheetJS in the calling thread. Only with `isolation: 'none'` (a worker cannot receive a
+   * function and always imports the installed `xlsx` itself); any other isolation is a defect
+   * when the layer is built. Defaults to a lazy `import('xlsx')`. Missing, non-SheetJS, or
+   * pre-0.20.3 modules fail with `SheetJsUnavailableError`.
+   */
+  readonly loadSheetJs?: SheetJsLoader
+}
+
+const decodeText = (bytes: Uint8Array) => new TextDecoder('utf-8', { fatal: false }).decode(bytes)
+
+type ParsedFileExtractor = WorkerExtractor
+
+/** Build the Node `FileExtractor` from validated limits and the parser runner. */
+const makeFileExtractor = (
+  limits: FileExtractorLimits,
+  extractParsed: ParsedFileExtractor
+): FileExtractorApi => ({
+  extract: input =>
+    Effect.gen(function* () {
+      const format = fileFormatFor(input)
+
+      if (format === undefined)
+        return yield* Effect.fail(
+          new UnsupportedFileFormatError({ filename: input.filename, mediaType: input.mediaType })
+        )
+
+      yield* Effect.annotateCurrentSpan({
+        'file_extractor.format': format,
+        'file_extractor.file_size': input.bytes.byteLength
+      })
+
+      if (input.bytes.byteLength > limits.maxInputBytes)
+        return yield* Effect.fail(
+          new FileExtractionError({ message: 'File exceeds the extraction size limit', format })
+        )
+
+      if (isParsedFileFormat(format)) return yield* extractParsed(input, format, limits)
+
+      // Text formats are only decoded and sanitized; no parser reads them.
+      return yield* makeExtractedFile(decodeText(input.bytes), { format, title: input.filename })
+    }).pipe(Effect.withSpan('FileExtractor.extract'))
+})
+
+const parsedFileExtractor = (
+  options: FileExtractorOptions
+): Effect.Effect<ParsedFileExtractor, Schema.SchemaError> => {
+  const isolation = options.isolation ?? 'worker'
+
+  if (isolation === 'none') {
+    const loader = options.loadSheetJs ?? defaultSheetJsLoader
+
+    return Effect.succeed((input, format: ParsedFileFormat, limits) =>
+      extractParsedFile(input, format, limits, loader)
+    )
+  }
+
+  if (options.loadSheetJs !== undefined)
+    return Effect.die(
+      new Error(
+        'FileExtractorOptions.loadSheetJs runs SheetJS in the calling thread and needs isolation: "none"'
+      )
+    )
+
+  const overrides = isolation === 'worker' ? {} : isolation
+  const timeoutMs = overrides.timeoutMs ?? defaultWorkerIsolation.timeoutMs
+
+  return Schema.decodeUnknownEffect(WorkerIsolationSettings)({
+    maxOldGenerationSizeMb:
+      overrides.maxOldGenerationSizeMb ?? defaultWorkerIsolation.maxOldGenerationSizeMb,
+    maxYoungGenerationSizeMb:
+      overrides.maxYoungGenerationSizeMb ?? defaultWorkerIsolation.maxYoungGenerationSizeMb,
+    stackSizeMb: overrides.stackSizeMb ?? defaultWorkerIsolation.stackSizeMb,
+    timeoutMs,
+    maxConcurrentWorkers:
+      overrides.maxConcurrentWorkers ?? defaultWorkerIsolation.maxConcurrentWorkers,
+    maxQueueWaitMs: overrides.maxQueueWaitMs ?? timeoutMs
+  }).pipe(
+    Effect.flatMap(settings =>
+      makeWorkerExtractor(settings, overrides.workerUrl ?? defaultExtractionWorkerUrl())
+    )
+  )
+}
+
+/**
+ * Node `FileExtractor` layer with custom limits, isolation, or (in-process) SheetJS loader.
+ * Invalid limits or isolation settings are defects.
+ */
+export const makeFileExtractorLayer = (options: FileExtractorOptions = {}) =>
+  Layer.effect(
+    FileExtractor,
+    Effect.gen(function* () {
+      const limits = yield* Schema.decodeUnknownEffect(FileExtractorLimits)({
+        ...defaultFileExtractorLimits,
+        ...options.limits
+      })
+
+      const extractParsed = yield* parsedFileExtractor(options)
+
+      return FileExtractor.of(makeFileExtractor(limits, extractParsed))
+    }).pipe(Effect.orDie)
+  )
+
+/**
+ * Node `FileExtractor` layer with the default limits, worker isolation, and lazy SheetJS loading.
+ */
+export const FileExtractorLayer = makeFileExtractorLayer()