@syncmatters/connector-sdk 1.0.20 → 1.0.21

package/docs/09-testing.md

@@ -135,6 +135,17 @@ To disable those tests use `cannotTestReason` instead
   contract under "What each test needs" below. Use `withIssueSimulators` /
   `UpsertIssueSimulator` (`verifyFields`, expected issue `type` + `fatal`) to deliberately
   exercise your `upsertClean` issue reporting.
+- **File fields in `upsertPrepare`.** When the object has an upsert field of `type: "file"`,
+  every `upsertPrepare` call (upsert, delete and upsertClean tests) carries `withFileField`
+  set to its path (a field with `constraints: { mandatory: "add" }` is preferred, else the
+  first file field). Put an `SDK.FileProvider` at that path in `insert` (and `update`), and
+  return a **fresh provider on every call**: the harness passes the connector a clone
+  (`SDK.utilities.clone(row, { withFileProviders: true })`), so the connector may close what
+  it is handed, and the harness closes your originals and its clones once the test has
+  verified them ([13-file-fields.md](./13-file-fields.md)). A file field listed in `verifyFields` is
+  compared by bytes with `FileProvider.equals()`: the query-back must return a provider with
+  the same content. The harness never adds the file field to the query-back on its own,
+  since that downloads the content; list it in `verifyFields` or `fields` to opt in.
 - delete features support soft-delete verification — `isDeleted: { path, valueWhenDeleted }`
   checks a flag field instead of row absence, and `afterDeleteMaxIndexWaitTimeMs` tolerates
   APIs whose deletions surface asynchronously.

package/docs/10-style-and-pitfalls.md

@@ -119,7 +119,9 @@
 The two you will use constantly (they appear in nearly every fleet connector):
 
 - `SDK.utilities.clone(value)` — deep clone. Use before mutating anything you received or
-  return (metadata, rows, options) — shared references are how callers get corrupted.
+  return (metadata, rows, options) — shared references are how callers get corrupted. A
+  `FileProvider` in the value becomes an unreadable shim unless you pass
+  `{ withFileProviders: true }` ([13-file-fields.md](./13-file-fields.md)).
 - `SDK.utilities.tryGet(() => deeply.nested.maybe.missing)` — returns the value or
   `undefined`, never throws. The idiom for prodding uncertain API payloads:
   `const sig = tryGet(() => options.payload.headers["x-signature"][0]);`

package/docs/13-file-fields.md

@@ -82,10 +82,34 @@ SDK.utilities.fileProvider({ file: { path: tempPath, deleteOnClose: true } });
 | `save(path?)`                         | persist to disk, returns the path (pair with `SDK.utilities.tempFile`)  |
 | `length()`                            | size in bytes (e.g. for a `size` field or Content-Length header)        |
 | `close()`                             | release the resource — **always, in a `finally`**                       |
+| `clone()`                             | an independent provider over the same bytes; close it like any other    |
+| `equals(other)`                       | `true` when both hold the same bytes; `false` if either side is closed  |
 
 Parsing structured file content: `SDK.utilities.csvReader({ source: { fileProvider } })`
 (same idea for `xlsxReader`).
 
+## Cloning and comparing
+
+`clone()` returns an independent provider: closing the original does not close the clone, and
+the clone **must be closed too**. A clone of a temp-file provider (`deleteOnClose`) shares the
+file by reference count, so the file is removed only when the last holder closes. A provider
+dropped without `close()` is released when the runtime collects it, which may be much later, so
+closing stays the rule. Cloning a closed provider throws `ResourceAlreadyClosed`.
+
+Deep-copying a row that holds a file:
+
+- `SDK.utilities.clone(row)` copies the data and replaces each provider with a **shim**. The
+  shim serialises like a provider (`"[object FileProvider]"`) and needs no close, but every read
+  (`stream()`, `length()`, `save()`, `blob()`, `formDataValue()`, `clone()`, `equals()`) throws
+  `SCRIPT_FILE_PROVIDER_SHALLOW_CLONE`. That is what a snapshot for logging wants.
+- `SDK.utilities.clone(row, { withFileProviders: true })` clones each provider with `clone()`,
+  so the copy can read the files. The code that made the copy owns its providers and must
+  close them.
+
+`equals(other)` compares bytes: lengths first, then both streams chunk by chunk, without
+reading whole files into memory. It resolves `false` rather than throwing when either side has
+been closed.
+
 ## Upserting: the file arrives as a field value
 
 The upsert row carries a `FileProvider` at the file field's position. Stream it out and close
@@ -121,3 +145,9 @@ async upsert(options) {
 3. **Close what you open.** Providers can be backed by temp files; `close()` in a `finally`
    on both the query and upsert paths.
 
+## Testing
+
+The connector test harness exercises file fields through the upsert, delete and upsertClean
+tests: it asks `upsertPrepare` for a file at `withFileField`, passes the connector a clone, and compares a file
+field listed in `verifyFields` by bytes. See
+[09-testing.md](./09-testing.md#preparecleanup-hooks-and-their-data-types).

package/lib/file-provider-buffer.d.ts

@@ -7,5 +7,7 @@ export declare class FileProviderBuffer implements FileProvider {
     blob(fileName?: string): Promise<Blob>;
     save(path?: string): Promise<string>;
     close(): Promise<void>;
+    clone(): FileProvider;
+    equals(other: FileProvider): Promise<boolean>;
     toJSON(): string;
 }

package/lib/file-provider-disk.d.ts

@@ -7,5 +7,7 @@ export declare class FileProviderDisk implements FileProvider {
     blob(fileName?: string): Promise<Blob>;
     save(path?: string): Promise<string>;
     close(): Promise<void>;
+    clone(): FileProvider;
+    equals(other: FileProvider): Promise<boolean>;
     toJSON(): string;
 }

package/lib/file-provider-string.d.ts

@@ -7,5 +7,7 @@ export declare class FileProviderString implements FileProvider {
     blob(fileName?: string): Promise<Blob>;
     save(path?: string): Promise<string>;
     close(): Promise<void>;
+    clone(): FileProvider;
+    equals(other: FileProvider): Promise<boolean>;
     toJSON(): string;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@syncmatters/connector-sdk",
-  "version": "1.0.20",
+  "version": "1.0.21",
   "description": "TypeScript type definitions for the SyncMatters connector SDK (types only - connectors execute on the SyncMatters platform)",
   "types": "./index.d.ts",
   "exports": {
@@ -12,9 +12,9 @@
   "license": "MIT",
   "author": "SyncMatters",
   "homepage": "https://syncmatters.com",
-  "typesContentHash": "376c97b772af51a69f5155aff7c80362062a74710e0672b3dd0582679b5cfffb",
+  "typesContentHash": "cbce2eec280ba657cbe2b0aa321b46b3578ab203622d95a3030beb8e5180cd78",
   "dependencies": {
     "@types/node": "*",
-    "@syncmatters/script-api": "^1.0.21"
+    "@syncmatters/script-api": "^1.0.23"
   }
 }