deepline 0.1.320 → 0.2.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -157,7 +157,10 @@ export const SDK_RELEASE = {
157
157
  // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
158
158
  // 0.1.254 removes the internal operations tree from the published SDK CLI.
159
159
  // Operators use the checkout-local deepline-admin binary instead.
160
- version: '0.1.320',
160
+ // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
161
+ // exposed storage-dependent synchronous access. This deliberate minor
162
+ // release keeps lazy paging semantics independent of row residency.
163
+ version: '0.2.0',
161
164
  contracts: {
162
165
  api: {
163
166
  name: 'sdk-http-api',
@@ -105,17 +105,14 @@ export type PlayDatasetTransformOptions = {
105
105
  * runtime control. Use `count()` and `peek()` for bounded inspection. Use
106
106
  * `materialize(limit)` or async iteration only when the dataset is intentionally
107
107
  * small and bounded. `PlayDataset` intentionally does not expose `.rows`,
108
- * `.toArray()`, or other array aliases; those hide the runtime cost of loading
109
- * persisted rows into memory.
108
+ * `.toArray()`, `.length`, numeric indexing, spread, or synchronous iteration;
109
+ * those hide the runtime cost of loading persisted rows into memory or make
110
+ * behavior depend on whether rows happen to be resident.
110
111
  *
111
112
  * @sdkReference runtime 190
112
113
  */
113
- export interface PlayDataset<T> extends AsyncIterable<T>, Iterable<T> {
114
+ export interface PlayDataset<T> extends AsyncIterable<T> {
114
115
  readonly [PLAY_DATASET_BRAND]: true;
115
- /** Authoritative row count when known without I/O. */
116
- readonly length: number;
117
- /** Resident row access. Throws when the requested row requires I/O. */
118
- readonly [index: number]: T;
119
116
  /** Dataset kind. */
120
117
  readonly datasetKind: PlayDatasetKind;
121
118
  /** Dataset id. */
@@ -413,7 +410,6 @@ export function trimSerializedPlayDatasetPreview<T>(
413
410
  }
414
411
 
415
412
  class DeferredPlayDataset<T> implements PlayDataset<T> {
416
- readonly [index: number]: T;
417
413
  readonly [PLAY_DATASET_BRAND] = true as const;
418
414
  readonly datasetKind: PlayDatasetKind;
419
415
  readonly datasetId: string;
@@ -456,15 +452,6 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
456
452
  this.resolvers = input.resolvers;
457
453
  }
458
454
 
459
- get length(): number {
460
- if (this.knownCount === null) {
461
- throw this.requiresAsyncAccess(
462
- 'The row count is not known until this lazy transform executes.',
463
- );
464
- }
465
- return this.knownCount;
466
- }
467
-
468
455
  async count(): Promise<number> {
469
456
  this.cachedCount = await this.resolvers.count();
470
457
  this.knownCount = this.cachedCount;
@@ -492,6 +479,9 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
492
479
  return undefined;
493
480
  }
494
481
  if (this.residentRows) return this.residentRows[normalized];
482
+ if (normalized < this.previewRows.length) {
483
+ return this.previewRows[normalized];
484
+ }
495
485
  if (this.resolvers.at) return await this.resolvers.at(normalized);
496
486
  let current = 0;
497
487
  for await (const row of this.resolvers.iterate()) {
@@ -591,33 +581,6 @@ class DeferredPlayDataset<T> implements PlayDataset<T> {
591
581
  }
592
582
  }
593
583
 
594
- [Symbol.iterator](): Iterator<T> {
595
- if (!this.residentRows) {
596
- throw this.requiresAsyncAccess(
597
- 'Synchronous iteration is available only when every row is resident.',
598
- );
599
- }
600
- return this.residentRows[Symbol.iterator]();
601
- }
602
-
603
- residentAt(index: number): T | undefined {
604
- if (this.knownCount !== null && index >= this.knownCount) return undefined;
605
- if (!this.residentRows) {
606
- throw this.requiresAsyncAccess(
607
- `Row ${index} is not resident and may require dataset paging.`,
608
- );
609
- }
610
- return this.residentRows[index];
611
- }
612
-
613
- private requiresAsyncAccess(detail: string): Error {
614
- return new Error(
615
- `PLAY_DATASET_REQUIRES_ASYNC_ACCESS: ${detail} ` +
616
- `Dataset Handle ${this.sourceLabel ?? this.datasetId}. ` +
617
- 'Use await dataset.first(), await dataset.at(index), await dataset.materialize(limit), or for await...of.',
618
- );
619
- }
620
-
621
584
  toJSON() {
622
585
  return {
623
586
  kind: 'dataset' as const,
@@ -802,8 +765,28 @@ export function createDeferredPlayDataset<T>(input: {
802
765
  const boundMethods = new Map<PropertyKey, unknown>();
803
766
  const dataset = new Proxy(target, {
804
767
  get(dataset, property) {
768
+ if (property === 'length') {
769
+ throw datasetAsyncOnlyError(
770
+ dataset,
771
+ 'Dataset Handles do not expose synchronous .length.',
772
+ 'Use await dataset.count().',
773
+ );
774
+ }
805
775
  if (typeof property === 'string' && /^(0|[1-9]\d*)$/.test(property)) {
806
- return dataset.residentAt(Number(property));
776
+ throw datasetAsyncOnlyError(
777
+ dataset,
778
+ `Dataset Handles do not expose synchronous row indexing (${property}).`,
779
+ `Use await dataset.at(${property}) or await dataset.first().`,
780
+ );
781
+ }
782
+ if (property === Symbol.iterator) {
783
+ return () => {
784
+ throw datasetAsyncOnlyError(
785
+ dataset,
786
+ 'Dataset Handles do not support synchronous iteration.',
787
+ 'Use for await...of or await dataset.materialize(limit).',
788
+ );
789
+ };
807
790
  }
808
791
  const value = Reflect.get(dataset, property, dataset);
809
792
  if (typeof value !== 'function') return value;
@@ -817,8 +800,10 @@ export function createDeferredPlayDataset<T>(input: {
817
800
  property === 'length' ||
818
801
  (typeof property === 'string' && /^(0|[1-9]\d*)$/.test(property))
819
802
  ) {
820
- throw new Error(
821
- 'PLAY_DATASET_READ_ONLY: Dataset Handle rows cannot be assigned directly.',
803
+ throw datasetAsyncOnlyError(
804
+ target,
805
+ 'Dataset Handles do not support synchronous array assignment.',
806
+ 'Transform rows with dataset.map(...) or explicitly materialize a bounded array.',
822
807
  );
823
808
  }
824
809
  return false;
@@ -831,6 +816,17 @@ export function createDeferredPlayDataset<T>(input: {
831
816
  return dataset;
832
817
  }
833
818
 
819
+ function datasetAsyncOnlyError(
820
+ dataset: Pick<PlayDataset<unknown>, 'datasetId' | 'sourceLabel'>,
821
+ detail: string,
822
+ guidance: string,
823
+ ): Error {
824
+ return new Error(
825
+ `PLAY_DATASET_ASYNC_ONLY: ${detail} ` +
826
+ `Dataset Handle ${dataset.sourceLabel ?? dataset.datasetId}. ${guidance}`,
827
+ );
828
+ }
829
+
834
830
  export function createPlayDataset<T>(
835
831
  rows: readonly T[],
836
832
  metadata?: {
package/dist/cli/index.js CHANGED
@@ -1037,7 +1037,10 @@ var SDK_RELEASE = {
1037
1037
  // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
1038
1038
  // 0.1.254 removes the internal operations tree from the published SDK CLI.
1039
1039
  // Operators use the checkout-local deepline-admin binary instead.
1040
- version: "0.1.320",
1040
+ // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
1041
+ // exposed storage-dependent synchronous access. This deliberate minor
1042
+ // release keeps lazy paging semantics independent of row residency.
1043
+ version: "0.2.0",
1041
1044
  contracts: {
1042
1045
  api: {
1043
1046
  name: "sdk-http-api",
@@ -11991,7 +11994,7 @@ async function traceCliSpan(phase, fields, run) {
11991
11994
 
11992
11995
  // src/cli/play-check-hints.ts
11993
11996
  var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline tools describe <tool> --json`. Use `toolExecutionResult.toolResponse.raw` for provider/tool-specific scalar fields, and `toolExecutionResult.extractedLists.<name>.get()` for declared row/list outputs.";
11994
- var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy and durable. Complete resident handles support read-only length/index/iteration. For paged rows use `.first()`, `.at(index)`, `.peek(n)`, `.materialize(limit)`, or async iteration; do not use `.rows` or `.toArray()`.";
11997
+ var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy, durable, and async-only. Use `.count()`, `.first()`, `.at(index)`, `.peek(n)`, `.materialize(limit)`, or async iteration; do not use `.length`, numeric indexing, spread, synchronous iteration, `.rows`, or `.toArray()`.";
11995
11998
  var ROW_PROPERTY_HINT = "Deepline hint: this row type only contains fields produced by the CSV/schema and previous map steps. Check source column casing and the exact output field names from earlier steps before scaling.";
11996
11999
  var TOOLS_EXECUTE_SIGNATURE_HINT = "Deepline hint: ctx.tools.execute requires a request object: `ctx.tools.execute({ id, tool, input, description })`. The stable `id` is required for logs, metadata, and receipt attachment; provider-call reuse is based on play, tool, semantic input, auth scope, provider action version, and cache policy.";
11997
12000
  var RUN_PLAY_SIGNATURE_HINT = "Deepline hint: ctx.runPlay uses a stable key plus a composable child play reference. Direct-run-only or dataset-backed batch plays must be run directly, exported, then consumed by a separate play.";
@@ -12009,7 +12012,7 @@ function looksLikeInvalidExtractedGetter(error, sourceLine) {
12009
12012
  function looksLikeDatasetApiMisuse(error, sourceLine) {
12010
12013
  return /Property '(?:rows|toArray|forEach|map|filter|reduce)' does not exist on type '[^']*PlayDataset/.test(
12011
12014
  error
12012
- ) || /\b(?:\.rows|\.toArray\(\)|\.forEach\(|\.map\(|\.filter\(|\.reduce\()/.test(
12015
+ ) || /PlayDataset/.test(error) && (/Property 'length' does not exist/.test(error) || /can't be used to index type/.test(error) || /\[Symbol\.iterator\]/.test(error) || /not iterable/.test(error)) || /\b(?:\.rows|\.toArray\(\)|\.forEach\(|\.map\(|\.filter\(|\.reduce\()/.test(
12013
12016
  sourceLine
12014
12017
  );
12015
12018
  }
@@ -1022,7 +1022,10 @@ var SDK_RELEASE = {
1022
1022
  // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
1023
1023
  // 0.1.254 removes the internal operations tree from the published SDK CLI.
1024
1024
  // Operators use the checkout-local deepline-admin binary instead.
1025
- version: "0.1.320",
1025
+ // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
1026
+ // exposed storage-dependent synchronous access. This deliberate minor
1027
+ // release keeps lazy paging semantics independent of row residency.
1028
+ version: "0.2.0",
1026
1029
  contracts: {
1027
1030
  api: {
1028
1031
  name: "sdk-http-api",
@@ -12020,7 +12023,7 @@ async function traceCliSpan(phase, fields, run) {
12020
12023
 
12021
12024
  // src/cli/play-check-hints.ts
12022
12025
  var EXTRACTED_GETTER_ERROR_HINT = "Deepline hint: extractedValues/extractedLists .get() only works for declared Deepline getters listed by `deepline tools describe <tool> --json`. Use `toolExecutionResult.toolResponse.raw` for provider/tool-specific scalar fields, and `toolExecutionResult.extractedLists.<name>.get()` for declared row/list outputs.";
12023
- var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy and durable. Complete resident handles support read-only length/index/iteration. For paged rows use `.first()`, `.at(index)`, `.peek(n)`, `.materialize(limit)`, or async iteration; do not use `.rows` or `.toArray()`.";
12026
+ var DATASET_API_HINT = "Deepline hint: PlayDataset is lazy, durable, and async-only. Use `.count()`, `.first()`, `.at(index)`, `.peek(n)`, `.materialize(limit)`, or async iteration; do not use `.length`, numeric indexing, spread, synchronous iteration, `.rows`, or `.toArray()`.";
12024
12027
  var ROW_PROPERTY_HINT = "Deepline hint: this row type only contains fields produced by the CSV/schema and previous map steps. Check source column casing and the exact output field names from earlier steps before scaling.";
12025
12028
  var TOOLS_EXECUTE_SIGNATURE_HINT = "Deepline hint: ctx.tools.execute requires a request object: `ctx.tools.execute({ id, tool, input, description })`. The stable `id` is required for logs, metadata, and receipt attachment; provider-call reuse is based on play, tool, semantic input, auth scope, provider action version, and cache policy.";
12026
12029
  var RUN_PLAY_SIGNATURE_HINT = "Deepline hint: ctx.runPlay uses a stable key plus a composable child play reference. Direct-run-only or dataset-backed batch plays must be run directly, exported, then consumed by a separate play.";
@@ -12038,7 +12041,7 @@ function looksLikeInvalidExtractedGetter(error, sourceLine) {
12038
12041
  function looksLikeDatasetApiMisuse(error, sourceLine) {
12039
12042
  return /Property '(?:rows|toArray|forEach|map|filter|reduce)' does not exist on type '[^']*PlayDataset/.test(
12040
12043
  error
12041
- ) || /\b(?:\.rows|\.toArray\(\)|\.forEach\(|\.map\(|\.filter\(|\.reduce\()/.test(
12044
+ ) || /PlayDataset/.test(error) && (/Property 'length' does not exist/.test(error) || /can't be used to index type/.test(error) || /\[Symbol\.iterator\]/.test(error) || /not iterable/.test(error)) || /\b(?:\.rows|\.toArray\(\)|\.forEach\(|\.map\(|\.filter\(|\.reduce\()/.test(
12042
12045
  sourceLine
12043
12046
  );
12044
12047
  }
package/dist/index.d.mts CHANGED
@@ -3605,17 +3605,14 @@ type PlayDatasetTransformOptions = {
3605
3605
  * runtime control. Use `count()` and `peek()` for bounded inspection. Use
3606
3606
  * `materialize(limit)` or async iteration only when the dataset is intentionally
3607
3607
  * small and bounded. `PlayDataset` intentionally does not expose `.rows`,
3608
- * `.toArray()`, or other array aliases; those hide the runtime cost of loading
3609
- * persisted rows into memory.
3608
+ * `.toArray()`, `.length`, numeric indexing, spread, or synchronous iteration;
3609
+ * those hide the runtime cost of loading persisted rows into memory or make
3610
+ * behavior depend on whether rows happen to be resident.
3610
3611
  *
3611
3612
  * @sdkReference runtime 190
3612
3613
  */
3613
- interface PlayDataset<T> extends AsyncIterable<T>, Iterable<T> {
3614
+ interface PlayDataset<T> extends AsyncIterable<T> {
3614
3615
  readonly [PLAY_DATASET_BRAND]: true;
3615
- /** Authoritative row count when known without I/O. */
3616
- readonly length: number;
3617
- /** Resident row access. Throws when the requested row requires I/O. */
3618
- readonly [index: number]: T;
3619
3616
  /** Dataset kind. */
3620
3617
  readonly datasetKind: PlayDatasetKind;
3621
3618
  /** Dataset id. */
package/dist/index.d.ts CHANGED
@@ -3605,17 +3605,14 @@ type PlayDatasetTransformOptions = {
3605
3605
  * runtime control. Use `count()` and `peek()` for bounded inspection. Use
3606
3606
  * `materialize(limit)` or async iteration only when the dataset is intentionally
3607
3607
  * small and bounded. `PlayDataset` intentionally does not expose `.rows`,
3608
- * `.toArray()`, or other array aliases; those hide the runtime cost of loading
3609
- * persisted rows into memory.
3608
+ * `.toArray()`, `.length`, numeric indexing, spread, or synchronous iteration;
3609
+ * those hide the runtime cost of loading persisted rows into memory or make
3610
+ * behavior depend on whether rows happen to be resident.
3610
3611
  *
3611
3612
  * @sdkReference runtime 190
3612
3613
  */
3613
- interface PlayDataset<T> extends AsyncIterable<T>, Iterable<T> {
3614
+ interface PlayDataset<T> extends AsyncIterable<T> {
3614
3615
  readonly [PLAY_DATASET_BRAND]: true;
3615
- /** Authoritative row count when known without I/O. */
3616
- readonly length: number;
3617
- /** Resident row access. Throws when the requested row requires I/O. */
3618
- readonly [index: number]: T;
3619
3616
  /** Dataset kind. */
3620
3617
  readonly datasetKind: PlayDatasetKind;
3621
3618
  /** Dataset id. */
package/dist/index.js CHANGED
@@ -760,7 +760,10 @@ var SDK_RELEASE = {
760
760
  // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
761
761
  // 0.1.254 removes the internal operations tree from the published SDK CLI.
762
762
  // Operators use the checkout-local deepline-admin binary instead.
763
- version: "0.1.320",
763
+ // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
764
+ // exposed storage-dependent synchronous access. This deliberate minor
765
+ // release keeps lazy paging semantics independent of row residency.
766
+ version: "0.2.0",
764
767
  contracts: {
765
768
  api: {
766
769
  name: "sdk-http-api",
@@ -5842,14 +5845,6 @@ var DeferredPlayDataset = class {
5842
5845
  this.workProgress = input.workProgress;
5843
5846
  this.resolvers = input.resolvers;
5844
5847
  }
5845
- get length() {
5846
- if (this.knownCount === null) {
5847
- throw this.requiresAsyncAccess(
5848
- "The row count is not known until this lazy transform executes."
5849
- );
5850
- }
5851
- return this.knownCount;
5852
- }
5853
5848
  async count() {
5854
5849
  this.cachedCount = await this.resolvers.count();
5855
5850
  this.knownCount = this.cachedCount;
@@ -5873,6 +5868,9 @@ var DeferredPlayDataset = class {
5873
5868
  return void 0;
5874
5869
  }
5875
5870
  if (this.residentRows) return this.residentRows[normalized];
5871
+ if (normalized < this.previewRows.length) {
5872
+ return this.previewRows[normalized];
5873
+ }
5876
5874
  if (this.resolvers.at) return await this.resolvers.at(normalized);
5877
5875
  let current = 0;
5878
5876
  for await (const row of this.resolvers.iterate()) {
@@ -5942,28 +5940,6 @@ var DeferredPlayDataset = class {
5942
5940
  yield row;
5943
5941
  }
5944
5942
  }
5945
- [Symbol.iterator]() {
5946
- if (!this.residentRows) {
5947
- throw this.requiresAsyncAccess(
5948
- "Synchronous iteration is available only when every row is resident."
5949
- );
5950
- }
5951
- return this.residentRows[Symbol.iterator]();
5952
- }
5953
- residentAt(index) {
5954
- if (this.knownCount !== null && index >= this.knownCount) return void 0;
5955
- if (!this.residentRows) {
5956
- throw this.requiresAsyncAccess(
5957
- `Row ${index} is not resident and may require dataset paging.`
5958
- );
5959
- }
5960
- return this.residentRows[index];
5961
- }
5962
- requiresAsyncAccess(detail) {
5963
- return new Error(
5964
- `PLAY_DATASET_REQUIRES_ASYNC_ACCESS: ${detail} Dataset Handle ${this.sourceLabel ?? this.datasetId}. Use await dataset.first(), await dataset.at(index), await dataset.materialize(limit), or for await...of.`
5965
- );
5966
- }
5967
5943
  toJSON() {
5968
5944
  return {
5969
5945
  kind: "dataset",
@@ -6094,8 +6070,28 @@ function createDeferredPlayDataset(input) {
6094
6070
  const boundMethods = /* @__PURE__ */ new Map();
6095
6071
  const dataset = new Proxy(target, {
6096
6072
  get(dataset2, property) {
6073
+ if (property === "length") {
6074
+ throw datasetAsyncOnlyError(
6075
+ dataset2,
6076
+ "Dataset Handles do not expose synchronous .length.",
6077
+ "Use await dataset.count()."
6078
+ );
6079
+ }
6097
6080
  if (typeof property === "string" && /^(0|[1-9]\d*)$/.test(property)) {
6098
- return dataset2.residentAt(Number(property));
6081
+ throw datasetAsyncOnlyError(
6082
+ dataset2,
6083
+ `Dataset Handles do not expose synchronous row indexing (${property}).`,
6084
+ `Use await dataset.at(${property}) or await dataset.first().`
6085
+ );
6086
+ }
6087
+ if (property === Symbol.iterator) {
6088
+ return () => {
6089
+ throw datasetAsyncOnlyError(
6090
+ dataset2,
6091
+ "Dataset Handles do not support synchronous iteration.",
6092
+ "Use for await...of or await dataset.materialize(limit)."
6093
+ );
6094
+ };
6099
6095
  }
6100
6096
  const value = Reflect.get(dataset2, property, dataset2);
6101
6097
  if (typeof value !== "function") return value;
@@ -6106,8 +6102,10 @@ function createDeferredPlayDataset(input) {
6106
6102
  },
6107
6103
  set(_dataset, property) {
6108
6104
  if (property === "length" || typeof property === "string" && /^(0|[1-9]\d*)$/.test(property)) {
6109
- throw new Error(
6110
- "PLAY_DATASET_READ_ONLY: Dataset Handle rows cannot be assigned directly."
6105
+ throw datasetAsyncOnlyError(
6106
+ target,
6107
+ "Dataset Handles do not support synchronous array assignment.",
6108
+ "Transform rows with dataset.map(...) or explicitly materialize a bounded array."
6111
6109
  );
6112
6110
  }
6113
6111
  return false;
@@ -6119,6 +6117,11 @@ function createDeferredPlayDataset(input) {
6119
6117
  }
6120
6118
  return dataset;
6121
6119
  }
6120
+ function datasetAsyncOnlyError(dataset, detail, guidance) {
6121
+ return new Error(
6122
+ `PLAY_DATASET_ASYNC_ONLY: ${detail} Dataset Handle ${dataset.sourceLabel ?? dataset.datasetId}. ${guidance}`
6123
+ );
6124
+ }
6122
6125
  function createPlayDataset(rows, metadata) {
6123
6126
  const materializedRows = [...rows];
6124
6127
  return createDeferredPlayDataset({
package/dist/index.mjs CHANGED
@@ -686,7 +686,10 @@ var SDK_RELEASE = {
686
686
  // 0.1.253 makes play-page browser opening opt-in and retires --no-open.
687
687
  // 0.1.254 removes the internal operations tree from the published SDK CLI.
688
688
  // Operators use the checkout-local deepline-admin binary instead.
689
- version: "0.1.320",
689
+ // 0.2.0 makes Dataset Handles uniformly async-only after 0.1.320 briefly
690
+ // exposed storage-dependent synchronous access. This deliberate minor
691
+ // release keeps lazy paging semantics independent of row residency.
692
+ version: "0.2.0",
690
693
  contracts: {
691
694
  api: {
692
695
  name: "sdk-http-api",
@@ -5768,14 +5771,6 @@ var DeferredPlayDataset = class {
5768
5771
  this.workProgress = input.workProgress;
5769
5772
  this.resolvers = input.resolvers;
5770
5773
  }
5771
- get length() {
5772
- if (this.knownCount === null) {
5773
- throw this.requiresAsyncAccess(
5774
- "The row count is not known until this lazy transform executes."
5775
- );
5776
- }
5777
- return this.knownCount;
5778
- }
5779
5774
  async count() {
5780
5775
  this.cachedCount = await this.resolvers.count();
5781
5776
  this.knownCount = this.cachedCount;
@@ -5799,6 +5794,9 @@ var DeferredPlayDataset = class {
5799
5794
  return void 0;
5800
5795
  }
5801
5796
  if (this.residentRows) return this.residentRows[normalized];
5797
+ if (normalized < this.previewRows.length) {
5798
+ return this.previewRows[normalized];
5799
+ }
5802
5800
  if (this.resolvers.at) return await this.resolvers.at(normalized);
5803
5801
  let current = 0;
5804
5802
  for await (const row of this.resolvers.iterate()) {
@@ -5868,28 +5866,6 @@ var DeferredPlayDataset = class {
5868
5866
  yield row;
5869
5867
  }
5870
5868
  }
5871
- [Symbol.iterator]() {
5872
- if (!this.residentRows) {
5873
- throw this.requiresAsyncAccess(
5874
- "Synchronous iteration is available only when every row is resident."
5875
- );
5876
- }
5877
- return this.residentRows[Symbol.iterator]();
5878
- }
5879
- residentAt(index) {
5880
- if (this.knownCount !== null && index >= this.knownCount) return void 0;
5881
- if (!this.residentRows) {
5882
- throw this.requiresAsyncAccess(
5883
- `Row ${index} is not resident and may require dataset paging.`
5884
- );
5885
- }
5886
- return this.residentRows[index];
5887
- }
5888
- requiresAsyncAccess(detail) {
5889
- return new Error(
5890
- `PLAY_DATASET_REQUIRES_ASYNC_ACCESS: ${detail} Dataset Handle ${this.sourceLabel ?? this.datasetId}. Use await dataset.first(), await dataset.at(index), await dataset.materialize(limit), or for await...of.`
5891
- );
5892
- }
5893
5869
  toJSON() {
5894
5870
  return {
5895
5871
  kind: "dataset",
@@ -6020,8 +5996,28 @@ function createDeferredPlayDataset(input) {
6020
5996
  const boundMethods = /* @__PURE__ */ new Map();
6021
5997
  const dataset = new Proxy(target, {
6022
5998
  get(dataset2, property) {
5999
+ if (property === "length") {
6000
+ throw datasetAsyncOnlyError(
6001
+ dataset2,
6002
+ "Dataset Handles do not expose synchronous .length.",
6003
+ "Use await dataset.count()."
6004
+ );
6005
+ }
6023
6006
  if (typeof property === "string" && /^(0|[1-9]\d*)$/.test(property)) {
6024
- return dataset2.residentAt(Number(property));
6007
+ throw datasetAsyncOnlyError(
6008
+ dataset2,
6009
+ `Dataset Handles do not expose synchronous row indexing (${property}).`,
6010
+ `Use await dataset.at(${property}) or await dataset.first().`
6011
+ );
6012
+ }
6013
+ if (property === Symbol.iterator) {
6014
+ return () => {
6015
+ throw datasetAsyncOnlyError(
6016
+ dataset2,
6017
+ "Dataset Handles do not support synchronous iteration.",
6018
+ "Use for await...of or await dataset.materialize(limit)."
6019
+ );
6020
+ };
6025
6021
  }
6026
6022
  const value = Reflect.get(dataset2, property, dataset2);
6027
6023
  if (typeof value !== "function") return value;
@@ -6032,8 +6028,10 @@ function createDeferredPlayDataset(input) {
6032
6028
  },
6033
6029
  set(_dataset, property) {
6034
6030
  if (property === "length" || typeof property === "string" && /^(0|[1-9]\d*)$/.test(property)) {
6035
- throw new Error(
6036
- "PLAY_DATASET_READ_ONLY: Dataset Handle rows cannot be assigned directly."
6031
+ throw datasetAsyncOnlyError(
6032
+ target,
6033
+ "Dataset Handles do not support synchronous array assignment.",
6034
+ "Transform rows with dataset.map(...) or explicitly materialize a bounded array."
6037
6035
  );
6038
6036
  }
6039
6037
  return false;
@@ -6045,6 +6043,11 @@ function createDeferredPlayDataset(input) {
6045
6043
  }
6046
6044
  return dataset;
6047
6045
  }
6046
+ function datasetAsyncOnlyError(dataset, detail, guidance) {
6047
+ return new Error(
6048
+ `PLAY_DATASET_ASYNC_ONLY: ${detail} Dataset Handle ${dataset.sourceLabel ?? dataset.datasetId}. ${guidance}`
6049
+ );
6050
+ }
6048
6051
  function createPlayDataset(rows, metadata) {
6049
6052
  const materializedRows = [...rows];
6050
6053
  return createDeferredPlayDataset({
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "deepline",
3
- "version": "0.1.320",
3
+ "version": "0.2.0",
4
4
  "description": "Deepline SDK + CLI — B2B data enrichment powered by durable cloud execution",
5
5
  "license": "MIT",
6
6
  "repository": {