@farukada/aws-langgraph-dynamodb-ts 1.0.0-rc.2 → 1.0.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.
Files changed (409) hide show
  1. package/README.md +390 -193
  2. package/dist/{backfill → cjs/backfill}/backfill.d.ts +15 -12
  3. package/dist/cjs/backfill/backfill.js +177 -0
  4. package/dist/{checkpointer → cjs/checkpointer}/actions/delete-thread.d.ts +1 -1
  5. package/dist/cjs/checkpointer/actions/delete-thread.js +26 -0
  6. package/dist/{checkpointer → cjs/checkpointer}/actions/get-tuple.d.ts +4 -3
  7. package/dist/cjs/checkpointer/actions/get-tuple.js +22 -0
  8. package/dist/{checkpointer → cjs/checkpointer}/actions/list.d.ts +7 -4
  9. package/dist/cjs/checkpointer/actions/list.js +70 -0
  10. package/dist/{checkpointer → cjs/checkpointer}/actions/put-writes.d.ts +8 -6
  11. package/dist/cjs/checkpointer/actions/put-writes.js +21 -0
  12. package/dist/{checkpointer → cjs/checkpointer}/actions/put.d.ts +21 -15
  13. package/dist/cjs/checkpointer/actions/put.js +79 -0
  14. package/dist/{checkpointer → cjs/checkpointer}/internal/delta-history.d.ts +38 -26
  15. package/dist/cjs/checkpointer/internal/delta-history.js +131 -0
  16. package/dist/{checkpointer → cjs/checkpointer}/internal/listing.d.ts +4 -4
  17. package/dist/cjs/checkpointer/internal/listing.js +104 -0
  18. package/dist/{checkpointer → cjs/checkpointer}/internal/parse.d.ts +51 -15
  19. package/dist/cjs/checkpointer/internal/parse.js +184 -0
  20. package/dist/{checkpointer → cjs/checkpointer}/internal/pending-writes.d.ts +64 -25
  21. package/dist/cjs/checkpointer/internal/pending-writes.js +241 -0
  22. package/dist/{checkpointer → cjs/checkpointer}/internal/read.d.ts +15 -10
  23. package/dist/cjs/checkpointer/internal/read.js +132 -0
  24. package/dist/{checkpointer → cjs/checkpointer}/internal/rows.d.ts +94 -21
  25. package/dist/cjs/checkpointer/internal/rows.js +356 -0
  26. package/dist/{checkpointer → cjs/checkpointer}/internal/setup.d.ts +13 -20
  27. package/dist/cjs/checkpointer/internal/setup.js +25 -0
  28. package/dist/{checkpointer → cjs/checkpointer}/saver.d.ts +72 -36
  29. package/dist/cjs/checkpointer/saver.js +56 -0
  30. package/dist/{checkpointer → cjs/checkpointer}/types.d.ts +1 -1
  31. package/dist/cjs/checkpointer/types.js +2 -0
  32. package/dist/{factory → cjs/factory}/factory.d.ts +25 -20
  33. package/dist/cjs/factory/factory.js +137 -0
  34. package/dist/{factory → cjs/factory}/types.d.ts +12 -12
  35. package/dist/cjs/factory/types.js +2 -0
  36. package/dist/{history → cjs/history}/actions/add-messages.d.ts +18 -10
  37. package/dist/cjs/history/actions/add-messages.js +17 -0
  38. package/dist/{history → cjs/history}/actions/clear.d.ts +1 -1
  39. package/dist/cjs/history/actions/clear.js +29 -0
  40. package/dist/{history → cjs/history}/actions/get-messages.d.ts +11 -9
  41. package/dist/cjs/history/actions/get-messages.js +58 -0
  42. package/dist/{history → cjs/history}/actions/list-sessions.d.ts +3 -3
  43. package/dist/cjs/history/actions/list-sessions.js +67 -0
  44. package/dist/{history → cjs/history}/actions/reconcile-count.d.ts +13 -9
  45. package/dist/cjs/history/actions/reconcile-count.js +8 -0
  46. package/dist/{history → cjs/history}/chat-message-history.d.ts +62 -30
  47. package/dist/cjs/history/chat-message-history.js +61 -0
  48. package/dist/{history → cjs/history}/internal/append.d.ts +64 -32
  49. package/dist/cjs/history/internal/append.js +267 -0
  50. package/dist/{history → cjs/history}/internal/message-read.d.ts +3 -3
  51. package/dist/cjs/history/internal/message-read.js +93 -0
  52. package/dist/{history → cjs/history}/internal/parse.d.ts +2 -2
  53. package/dist/cjs/history/internal/parse.js +113 -0
  54. package/dist/{history → cjs/history}/internal/rows.d.ts +11 -10
  55. package/dist/cjs/history/internal/rows.js +96 -0
  56. package/dist/{history → cjs/history}/internal/session.d.ts +41 -22
  57. package/dist/cjs/history/internal/session.js +296 -0
  58. package/dist/{history → cjs/history}/internal/setup.d.ts +2 -2
  59. package/dist/cjs/history/internal/setup.js +60 -0
  60. package/dist/{history → cjs/history}/session-adapter.d.ts +0 -6
  61. package/dist/cjs/history/session-adapter.js +38 -0
  62. package/dist/{history → cjs/history}/types.d.ts +18 -15
  63. package/dist/cjs/history/types.js +2 -0
  64. package/dist/{index.d.ts → cjs/index.d.ts} +27 -27
  65. package/dist/cjs/index.js +25 -0
  66. package/dist/cjs/package.json +1 -0
  67. package/dist/{shared → cjs/shared}/adapter.d.ts +27 -16
  68. package/dist/cjs/shared/adapter.js +70 -0
  69. package/dist/cjs/shared/clock.js +14 -0
  70. package/dist/{shared → cjs/shared}/codec/codec.d.ts +37 -20
  71. package/dist/cjs/shared/codec/codec.js +162 -0
  72. package/dist/{shared → cjs/shared}/codec/compression.d.ts +9 -4
  73. package/dist/cjs/shared/codec/compression.js +45 -0
  74. package/dist/cjs/shared/codec/json-serde.js +58 -0
  75. package/dist/{shared → cjs/shared}/codec/s3/client-types.d.ts +2 -1
  76. package/dist/cjs/shared/codec/s3/client-types.js +6 -0
  77. package/dist/{shared → cjs/shared}/codec/s3/client.d.ts +25 -7
  78. package/dist/cjs/shared/codec/s3/client.js +78 -0
  79. package/dist/{shared → cjs/shared}/codec/s3/config.d.ts +12 -7
  80. package/dist/cjs/shared/codec/s3/config.js +92 -0
  81. package/dist/{shared → cjs/shared}/codec/s3/lifecycle.d.ts +71 -17
  82. package/dist/cjs/shared/codec/s3/lifecycle.js +223 -0
  83. package/dist/{shared → cjs/shared}/codec/s3/offloader.d.ts +42 -29
  84. package/dist/cjs/shared/codec/s3/offloader.js +289 -0
  85. package/dist/cjs/shared/concurrency.js +31 -0
  86. package/dist/{shared → cjs/shared}/dynamodb/abort.d.ts +2 -2
  87. package/dist/cjs/shared/dynamodb/abort.js +16 -0
  88. package/dist/{shared → cjs/shared}/dynamodb/batch-write.d.ts +2 -2
  89. package/dist/cjs/shared/dynamodb/batch-write.js +79 -0
  90. package/dist/cjs/shared/dynamodb/cancellation.js +37 -0
  91. package/dist/{shared → cjs/shared}/dynamodb/client.d.ts +24 -22
  92. package/dist/cjs/shared/dynamodb/client.js +40 -0
  93. package/dist/{shared → cjs/shared}/dynamodb/idempotent-write.d.ts +64 -19
  94. package/dist/cjs/shared/dynamodb/idempotent-write.js +173 -0
  95. package/dist/{shared → cjs/shared}/dynamodb/paginate.d.ts +2 -2
  96. package/dist/cjs/shared/dynamodb/paginate.js +90 -0
  97. package/dist/{shared → cjs/shared}/dynamodb/partition-delete.d.ts +6 -6
  98. package/dist/cjs/shared/dynamodb/partition-delete.js +177 -0
  99. package/dist/{shared → cjs/shared}/dynamodb/recency-index.d.ts +27 -15
  100. package/dist/cjs/shared/dynamodb/recency-index.js +146 -0
  101. package/dist/{shared → cjs/shared}/dynamodb/retry.d.ts +37 -6
  102. package/dist/cjs/shared/dynamodb/retry.js +193 -0
  103. package/dist/cjs/shared/dynamodb/row-size.d.ts +33 -0
  104. package/dist/cjs/shared/dynamodb/row-size.js +30 -0
  105. package/dist/{shared → cjs/shared}/dynamodb/table-schema.d.ts +27 -18
  106. package/dist/cjs/shared/dynamodb/table-schema.js +52 -0
  107. package/dist/{shared → cjs/shared}/errors/base-error.d.ts +42 -7
  108. package/dist/cjs/shared/errors/base-error.js +73 -0
  109. package/dist/{shared → cjs/shared}/errors/boundary.d.ts +29 -14
  110. package/dist/cjs/shared/errors/boundary.js +61 -0
  111. package/dist/cjs/shared/errors/classify.d.ts +206 -0
  112. package/dist/cjs/shared/errors/classify.js +232 -0
  113. package/dist/{shared → cjs/shared}/errors/error-code.d.ts +17 -10
  114. package/dist/cjs/shared/errors/error-code.js +27 -0
  115. package/dist/{shared → cjs/shared}/errors/errors.d.ts +75 -9
  116. package/dist/cjs/shared/errors/errors.js +123 -0
  117. package/dist/cjs/shared/logging/logger.js +30 -0
  118. package/dist/{shared → cjs/shared}/logging/redaction.d.ts +8 -4
  119. package/dist/cjs/shared/logging/redaction.js +145 -0
  120. package/dist/{shared → cjs/shared}/logging/secret-patterns.d.ts +30 -7
  121. package/dist/cjs/shared/logging/secret-patterns.js +93 -0
  122. package/dist/cjs/shared/logging/truncate.js +31 -0
  123. package/dist/{shared → cjs/shared}/options.d.ts +27 -11
  124. package/dist/cjs/shared/options.js +2 -0
  125. package/dist/cjs/shared/ulid.js +83 -0
  126. package/dist/{shared → cjs/shared}/validation/collaborators.d.ts +21 -2
  127. package/dist/cjs/shared/validation/collaborators.js +79 -0
  128. package/dist/{shared → cjs/shared}/validation/option-shape.d.ts +7 -5
  129. package/dist/cjs/shared/validation/option-shape.js +31 -0
  130. package/dist/{shared → cjs/shared}/validation/options.d.ts +4 -4
  131. package/dist/cjs/shared/validation/options.js +166 -0
  132. package/dist/cjs/shared/validation/primitives.js +114 -0
  133. package/dist/{shared → cjs/shared}/validation/ttl.d.ts +26 -9
  134. package/dist/cjs/shared/validation/ttl.js +52 -0
  135. package/dist/{store → cjs/store}/actions/list-namespaces.d.ts +5 -5
  136. package/dist/cjs/store/actions/list-namespaces.js +92 -0
  137. package/dist/{store → cjs/store}/actions/put.d.ts +11 -4
  138. package/dist/cjs/store/actions/put.js +49 -0
  139. package/dist/{store → cjs/store}/actions/reconcile-vector-index.d.ts +5 -5
  140. package/dist/cjs/store/actions/reconcile-vector-index.js +13 -0
  141. package/dist/{store → cjs/store}/actions/search.d.ts +2 -2
  142. package/dist/cjs/store/actions/search.js +26 -0
  143. package/dist/cjs/store/internal/batch-plan.d.ts +56 -0
  144. package/dist/cjs/store/internal/batch-plan.js +32 -0
  145. package/dist/{store → cjs/store}/internal/filter.d.ts +3 -3
  146. package/dist/cjs/store/internal/filter.js +64 -0
  147. package/dist/cjs/store/internal/get-item.d.ts +77 -0
  148. package/dist/cjs/store/internal/get-item.js +58 -0
  149. package/dist/{store → cjs/store}/internal/item-write.d.ts +72 -32
  150. package/dist/cjs/store/internal/item-write.js +181 -0
  151. package/dist/{store → cjs/store}/internal/parse.d.ts +15 -10
  152. package/dist/cjs/store/internal/parse.js +180 -0
  153. package/dist/{store → cjs/store}/internal/rows.d.ts +38 -34
  154. package/dist/cjs/store/internal/rows.js +166 -0
  155. package/dist/{store → cjs/store}/internal/semantic-search.d.ts +2 -2
  156. package/dist/cjs/store/internal/semantic-search.js +211 -0
  157. package/dist/{store → cjs/store}/internal/setup.d.ts +10 -15
  158. package/dist/cjs/store/internal/setup.js +103 -0
  159. package/dist/{store → cjs/store}/internal/table-search.d.ts +5 -5
  160. package/dist/cjs/store/internal/table-search.js +123 -0
  161. package/dist/{store → cjs/store}/internal/vector-index.d.ts +26 -15
  162. package/dist/cjs/store/internal/vector-index.js +269 -0
  163. package/dist/{store → cjs/store}/store.d.ts +82 -39
  164. package/dist/cjs/store/store.js +97 -0
  165. package/dist/{store → cjs/store}/types.d.ts +25 -10
  166. package/dist/cjs/store/types.js +2 -0
  167. package/dist/cjs/store/vector-backend.js +4 -0
  168. package/dist/esm/backfill/backfill.d.ts +171 -0
  169. package/dist/esm/backfill/backfill.js +170 -0
  170. package/dist/{checkpointer/actions/delete-thread.js → esm/checkpointer/actions/delete-thread.d.ts} +4 -26
  171. package/dist/esm/checkpointer/actions/delete-thread.js +23 -0
  172. package/dist/{checkpointer/actions/get-tuple.js → esm/checkpointer/actions/get-tuple.d.ts} +7 -24
  173. package/dist/esm/checkpointer/actions/get-tuple.js +19 -0
  174. package/dist/esm/checkpointer/actions/list.d.ts +55 -0
  175. package/dist/esm/checkpointer/actions/list.js +67 -0
  176. package/dist/{checkpointer/actions/put-writes.js → esm/checkpointer/actions/put-writes.d.ts} +10 -37
  177. package/dist/esm/checkpointer/actions/put-writes.js +18 -0
  178. package/dist/esm/checkpointer/actions/put.d.ts +95 -0
  179. package/dist/esm/checkpointer/actions/put.js +75 -0
  180. package/dist/esm/checkpointer/internal/delta-history.d.ts +124 -0
  181. package/dist/esm/checkpointer/internal/delta-history.js +126 -0
  182. package/dist/{checkpointer/internal/listing.js → esm/checkpointer/internal/listing.d.ts} +22 -118
  183. package/dist/esm/checkpointer/internal/listing.js +95 -0
  184. package/dist/esm/checkpointer/internal/parse.d.ts +298 -0
  185. package/dist/esm/checkpointer/internal/parse.js +169 -0
  186. package/dist/esm/checkpointer/internal/pending-writes.d.ts +314 -0
  187. package/dist/esm/checkpointer/internal/pending-writes.js +229 -0
  188. package/dist/esm/checkpointer/internal/read.d.ts +135 -0
  189. package/dist/esm/checkpointer/internal/read.js +125 -0
  190. package/dist/esm/checkpointer/internal/rows.d.ts +644 -0
  191. package/dist/esm/checkpointer/internal/rows.js +323 -0
  192. package/dist/esm/checkpointer/internal/setup.d.ts +47 -0
  193. package/dist/esm/checkpointer/internal/setup.js +21 -0
  194. package/dist/{checkpointer/saver.js → esm/checkpointer/saver.d.ts} +84 -87
  195. package/dist/esm/checkpointer/saver.js +52 -0
  196. package/dist/esm/checkpointer/types.d.ts +51 -0
  197. package/dist/esm/checkpointer/types.js +1 -0
  198. package/dist/esm/factory/factory.d.ts +154 -0
  199. package/dist/esm/factory/factory.js +133 -0
  200. package/dist/esm/factory/types.d.ts +76 -0
  201. package/dist/esm/factory/types.js +1 -0
  202. package/dist/{history/actions/add-messages.js → esm/history/actions/add-messages.d.ts} +20 -26
  203. package/dist/esm/history/actions/add-messages.js +14 -0
  204. package/dist/{history/actions/clear.js → esm/history/actions/clear.d.ts} +4 -35
  205. package/dist/esm/history/actions/clear.js +26 -0
  206. package/dist/esm/history/actions/get-messages.d.ts +60 -0
  207. package/dist/esm/history/actions/get-messages.js +55 -0
  208. package/dist/esm/history/actions/list-sessions.d.ts +55 -0
  209. package/dist/esm/history/actions/list-sessions.js +64 -0
  210. package/dist/{history/actions/reconcile-count.js → esm/history/actions/reconcile-count.d.ts} +14 -16
  211. package/dist/esm/history/actions/reconcile-count.js +5 -0
  212. package/dist/{history/chat-message-history.js → esm/history/chat-message-history.d.ts} +76 -87
  213. package/dist/esm/history/chat-message-history.js +57 -0
  214. package/dist/esm/history/internal/append.d.ts +244 -0
  215. package/dist/esm/history/internal/append.js +259 -0
  216. package/dist/esm/history/internal/message-read.d.ts +84 -0
  217. package/dist/esm/history/internal/message-read.js +89 -0
  218. package/dist/esm/history/internal/parse.d.ts +153 -0
  219. package/dist/esm/history/internal/parse.js +105 -0
  220. package/dist/{history/internal/rows.js → esm/history/internal/rows.d.ts} +58 -112
  221. package/dist/esm/history/internal/rows.js +83 -0
  222. package/dist/esm/history/internal/session.d.ts +350 -0
  223. package/dist/esm/history/internal/session.js +285 -0
  224. package/dist/esm/history/internal/setup.d.ts +64 -0
  225. package/dist/esm/history/internal/setup.js +56 -0
  226. package/dist/{history/session-adapter.js → esm/history/session-adapter.d.ts} +25 -39
  227. package/dist/esm/history/session-adapter.js +34 -0
  228. package/dist/esm/history/types.d.ts +102 -0
  229. package/dist/esm/history/types.js +1 -0
  230. package/dist/esm/index.d.ts +53 -0
  231. package/dist/esm/index.js +10 -0
  232. package/dist/esm/shared/adapter.d.ts +146 -0
  233. package/dist/esm/shared/adapter.js +65 -0
  234. package/dist/{shared/clock.js → esm/shared/clock.d.ts} +3 -14
  235. package/dist/esm/shared/clock.js +9 -0
  236. package/dist/esm/shared/codec/codec.d.ts +336 -0
  237. package/dist/esm/shared/codec/codec.js +150 -0
  238. package/dist/esm/shared/codec/compression.d.ts +66 -0
  239. package/dist/esm/shared/codec/compression.js +40 -0
  240. package/dist/esm/shared/codec/json-serde.d.ts +80 -0
  241. package/dist/esm/shared/codec/json-serde.js +54 -0
  242. package/dist/esm/shared/codec/s3/client-types.d.ts +54 -0
  243. package/dist/esm/shared/codec/s3/client-types.js +3 -0
  244. package/dist/esm/shared/codec/s3/client.d.ts +63 -0
  245. package/dist/esm/shared/codec/s3/client.js +40 -0
  246. package/dist/{shared/codec/s3/config.js → esm/shared/codec/s3/config.d.ts} +45 -93
  247. package/dist/esm/shared/codec/s3/config.js +79 -0
  248. package/dist/esm/shared/codec/s3/lifecycle.d.ts +220 -0
  249. package/dist/esm/shared/codec/s3/lifecycle.js +214 -0
  250. package/dist/esm/shared/codec/s3/offloader.d.ts +428 -0
  251. package/dist/esm/shared/codec/s3/offloader.js +278 -0
  252. package/dist/{shared/concurrency.js → esm/shared/concurrency.d.ts} +2 -37
  253. package/dist/esm/shared/concurrency.js +27 -0
  254. package/dist/{shared/dynamodb/abort.js → esm/shared/dynamodb/abort.d.ts} +4 -16
  255. package/dist/esm/shared/dynamodb/abort.js +12 -0
  256. package/dist/esm/shared/dynamodb/batch-write.d.ts +86 -0
  257. package/dist/esm/shared/dynamodb/batch-write.js +74 -0
  258. package/dist/{shared/dynamodb/cancellation.js → esm/shared/dynamodb/cancellation.d.ts} +25 -53
  259. package/dist/esm/shared/dynamodb/cancellation.js +30 -0
  260. package/dist/{shared/dynamodb/client.js → esm/shared/dynamodb/client.d.ts} +74 -64
  261. package/dist/esm/shared/dynamodb/client.js +35 -0
  262. package/dist/{shared/dynamodb/idempotent-write.js → esm/shared/dynamodb/idempotent-write.d.ts} +172 -169
  263. package/dist/esm/shared/dynamodb/idempotent-write.js +153 -0
  264. package/dist/esm/shared/dynamodb/paginate.d.ts +111 -0
  265. package/dist/esm/shared/dynamodb/paginate.js +84 -0
  266. package/dist/esm/shared/dynamodb/partition-delete.d.ts +204 -0
  267. package/dist/esm/shared/dynamodb/partition-delete.js +171 -0
  268. package/dist/esm/shared/dynamodb/recency-index.d.ts +243 -0
  269. package/dist/esm/shared/dynamodb/recency-index.js +136 -0
  270. package/dist/esm/shared/dynamodb/retry.d.ts +317 -0
  271. package/dist/esm/shared/dynamodb/retry.js +180 -0
  272. package/dist/esm/shared/dynamodb/row-size.d.ts +33 -0
  273. package/dist/esm/shared/dynamodb/row-size.js +26 -0
  274. package/dist/{shared/dynamodb/table-schema.js → esm/shared/dynamodb/table-schema.d.ts} +57 -67
  275. package/dist/esm/shared/dynamodb/table-schema.js +43 -0
  276. package/dist/esm/shared/errors/base-error.d.ts +231 -0
  277. package/dist/esm/shared/errors/base-error.js +64 -0
  278. package/dist/esm/shared/errors/boundary.d.ts +86 -0
  279. package/dist/esm/shared/errors/boundary.js +54 -0
  280. package/dist/esm/shared/errors/classify.d.ts +206 -0
  281. package/dist/esm/shared/errors/classify.js +220 -0
  282. package/dist/{shared/errors/error-code.js → esm/shared/errors/error-code.d.ts} +39 -43
  283. package/dist/esm/shared/errors/error-code.js +24 -0
  284. package/dist/{shared/errors/errors.js → esm/shared/errors/errors.d.ts} +92 -98
  285. package/dist/esm/shared/errors/errors.js +110 -0
  286. package/dist/{shared/logging/logger.js → esm/shared/logging/logger.d.ts} +22 -52
  287. package/dist/esm/shared/logging/logger.js +25 -0
  288. package/dist/esm/shared/logging/redaction.d.ts +123 -0
  289. package/dist/esm/shared/logging/redaction.js +140 -0
  290. package/dist/{shared/logging/secret-patterns.js → esm/shared/logging/secret-patterns.d.ts} +46 -87
  291. package/dist/esm/shared/logging/secret-patterns.js +83 -0
  292. package/dist/{shared/logging/truncate.js → esm/shared/logging/truncate.d.ts} +6 -40
  293. package/dist/esm/shared/logging/truncate.js +25 -0
  294. package/dist/esm/shared/options.d.ts +100 -0
  295. package/dist/esm/shared/options.js +1 -0
  296. package/dist/{shared/ulid.js → esm/shared/ulid.d.ts} +4 -84
  297. package/dist/esm/shared/ulid.js +77 -0
  298. package/dist/{shared/validation/collaborators.js → esm/shared/validation/collaborators.d.ts} +37 -65
  299. package/dist/esm/shared/validation/collaborators.js +70 -0
  300. package/dist/{shared/validation/option-shape.js → esm/shared/validation/option-shape.d.ts} +14 -36
  301. package/dist/esm/shared/validation/option-shape.js +24 -0
  302. package/dist/esm/shared/validation/options.d.ts +145 -0
  303. package/dist/esm/shared/validation/options.js +156 -0
  304. package/dist/{shared/validation/primitives.js → esm/shared/validation/primitives.d.ts} +30 -125
  305. package/dist/esm/shared/validation/primitives.js +100 -0
  306. package/dist/esm/shared/validation/ttl.d.ts +94 -0
  307. package/dist/esm/shared/validation/ttl.js +46 -0
  308. package/dist/esm/store/actions/list-namespaces.d.ts +79 -0
  309. package/dist/esm/store/actions/list-namespaces.js +86 -0
  310. package/dist/esm/store/actions/put.d.ts +43 -0
  311. package/dist/esm/store/actions/put.js +46 -0
  312. package/dist/{store/actions/reconcile-vector-index.js → esm/store/actions/reconcile-vector-index.d.ts} +8 -16
  313. package/dist/esm/store/actions/reconcile-vector-index.js +10 -0
  314. package/dist/esm/store/actions/search.d.ts +38 -0
  315. package/dist/esm/store/actions/search.js +23 -0
  316. package/dist/esm/store/internal/batch-plan.d.ts +56 -0
  317. package/dist/esm/store/internal/batch-plan.js +28 -0
  318. package/dist/esm/store/internal/filter.d.ts +43 -0
  319. package/dist/esm/store/internal/filter.js +60 -0
  320. package/dist/esm/store/internal/get-item.d.ts +77 -0
  321. package/dist/esm/store/internal/get-item.js +54 -0
  322. package/dist/esm/store/internal/item-write.d.ts +270 -0
  323. package/dist/esm/store/internal/item-write.js +173 -0
  324. package/dist/esm/store/internal/parse.d.ts +230 -0
  325. package/dist/esm/store/internal/parse.js +169 -0
  326. package/dist/{store/internal/rows.js → esm/store/internal/rows.d.ts} +111 -199
  327. package/dist/esm/store/internal/rows.js +147 -0
  328. package/dist/esm/store/internal/semantic-search.d.ts +168 -0
  329. package/dist/esm/store/internal/semantic-search.js +200 -0
  330. package/dist/esm/store/internal/setup.d.ts +96 -0
  331. package/dist/esm/store/internal/setup.js +98 -0
  332. package/dist/esm/store/internal/table-search.d.ts +100 -0
  333. package/dist/esm/store/internal/table-search.js +119 -0
  334. package/dist/esm/store/internal/vector-index.d.ts +258 -0
  335. package/dist/esm/store/internal/vector-index.js +256 -0
  336. package/dist/{store/store.js → esm/store/store.d.ts} +99 -133
  337. package/dist/esm/store/store.js +93 -0
  338. package/dist/esm/store/types.d.ts +111 -0
  339. package/dist/esm/store/types.js +1 -0
  340. package/dist/esm/store/vector-backend.d.ts +104 -0
  341. package/dist/esm/store/vector-backend.js +1 -0
  342. package/package.json +50 -44
  343. package/dist/backfill/backfill.js +0 -393
  344. package/dist/checkpointer/actions/list.js +0 -142
  345. package/dist/checkpointer/actions/put.js +0 -195
  346. package/dist/checkpointer/internal/delta-history.js +0 -252
  347. package/dist/checkpointer/internal/parse.js +0 -372
  348. package/dist/checkpointer/internal/pending-writes.js +0 -588
  349. package/dist/checkpointer/internal/read.js +0 -264
  350. package/dist/checkpointer/internal/rows.js +0 -834
  351. package/dist/checkpointer/internal/setup.js +0 -72
  352. package/dist/checkpointer/types.js +0 -12
  353. package/dist/factory/factory.js +0 -266
  354. package/dist/factory/types.js +0 -10
  355. package/dist/history/actions/get-messages.js +0 -141
  356. package/dist/history/actions/list-sessions.js +0 -156
  357. package/dist/history/internal/append.js +0 -500
  358. package/dist/history/internal/message-read.js +0 -204
  359. package/dist/history/internal/parse.js +0 -252
  360. package/dist/history/internal/session.js +0 -628
  361. package/dist/history/internal/setup.js +0 -106
  362. package/dist/history/types.js +0 -12
  363. package/dist/index.js +0 -51
  364. package/dist/shared/adapter.js +0 -143
  365. package/dist/shared/codec/codec.js +0 -441
  366. package/dist/shared/codec/compression.js +0 -89
  367. package/dist/shared/codec/json-serde.js +0 -191
  368. package/dist/shared/codec/s3/client-types.js +0 -26
  369. package/dist/shared/codec/s3/client.js +0 -97
  370. package/dist/shared/codec/s3/lifecycle.js +0 -355
  371. package/dist/shared/codec/s3/offloader.js +0 -658
  372. package/dist/shared/dynamodb/batch-write.js +0 -173
  373. package/dist/shared/dynamodb/paginate.js +0 -188
  374. package/dist/shared/dynamodb/partition-delete.js +0 -340
  375. package/dist/shared/dynamodb/recency-index.js +0 -377
  376. package/dist/shared/dynamodb/retry.js +0 -463
  377. package/dist/shared/errors/base-error.js +0 -174
  378. package/dist/shared/errors/boundary.js +0 -143
  379. package/dist/shared/errors/classify.d.ts +0 -97
  380. package/dist/shared/errors/classify.js +0 -257
  381. package/dist/shared/logging/redaction.js +0 -316
  382. package/dist/shared/options.js +0 -11
  383. package/dist/shared/validation/options.js +0 -328
  384. package/dist/shared/validation/ttl.js +0 -132
  385. package/dist/store/actions/list-namespaces.js +0 -197
  386. package/dist/store/actions/put.js +0 -78
  387. package/dist/store/actions/search.js +0 -66
  388. package/dist/store/internal/batch-plan.d.ts +0 -26
  389. package/dist/store/internal/batch-plan.js +0 -109
  390. package/dist/store/internal/filter.js +0 -137
  391. package/dist/store/internal/get-item.d.ts +0 -45
  392. package/dist/store/internal/get-item.js +0 -115
  393. package/dist/store/internal/item-write.js +0 -463
  394. package/dist/store/internal/parse.js +0 -350
  395. package/dist/store/internal/semantic-search.js +0 -389
  396. package/dist/store/internal/setup.js +0 -223
  397. package/dist/store/internal/table-search.js +0 -213
  398. package/dist/store/internal/vector-index.js +0 -546
  399. package/dist/store/types.js +0 -15
  400. package/dist/store/vector-backend.js +0 -17
  401. /package/dist/{shared → cjs/shared}/clock.d.ts +0 -0
  402. /package/dist/{shared → cjs/shared}/codec/json-serde.d.ts +0 -0
  403. /package/dist/{shared → cjs/shared}/concurrency.d.ts +0 -0
  404. /package/dist/{shared → cjs/shared}/dynamodb/cancellation.d.ts +0 -0
  405. /package/dist/{shared → cjs/shared}/logging/logger.d.ts +0 -0
  406. /package/dist/{shared → cjs/shared}/logging/truncate.d.ts +0 -0
  407. /package/dist/{shared → cjs/shared}/ulid.d.ts +0 -0
  408. /package/dist/{shared → cjs/shared}/validation/primitives.d.ts +0 -0
  409. /package/dist/{store → cjs/store}/vector-backend.d.ts +0 -0
@@ -0,0 +1,181 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.deleteStoreItem = deleteStoreItem;
4
+ exports.assertRowFits = assertRowFits;
5
+ exports.persistRow = persistRow;
6
+ exports.putWithRevisionSwap = putWithRevisionSwap;
7
+ exports.isRetryExhausted = isRetryExhausted;
8
+ exports.verifyWriteLanded = verifyWriteLanded;
9
+ const codec_js_1 = require("../../shared/codec/codec.js");
10
+ const offloader_js_1 = require("../../shared/codec/s3/offloader.js");
11
+ const idempotent_write_js_1 = require("../../shared/dynamodb/idempotent-write.js");
12
+ const retry_js_1 = require("../../shared/dynamodb/retry.js");
13
+ const row_size_js_1 = require("../../shared/dynamodb/row-size.js");
14
+ const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
15
+ const base_error_js_1 = require("../../shared/errors/base-error.js");
16
+ const error_code_js_1 = require("../../shared/errors/error-code.js");
17
+ const errors_js_1 = require("../../shared/errors/errors.js");
18
+ const rows_js_1 = require("./rows.js");
19
+ const vector_index_js_1 = require("./vector-index.js");
20
+ async function repinOrResolve(context, key, error) {
21
+ if ((0, idempotent_write_js_1.isConditionalCheckFailed)(error)) {
22
+ const rejected = (0, idempotent_write_js_1.rejectedRow)(error);
23
+ return rejected === undefined ? undefined : (0, rows_js_1.existingFrom)(rejected);
24
+ }
25
+ if (isRetryExhausted(error) && (await (0, idempotent_write_js_1.isRowAbsent)(context, key)))
26
+ return undefined;
27
+ throw error;
28
+ }
29
+ async function removeObservedRow(context, key, existing) {
30
+ let observed = existing;
31
+ for (let attempt = 1; attempt <= idempotent_write_js_1.OVERWRITE_CAS_MAX_ATTEMPTS; attempt++) {
32
+ try {
33
+ await (0, idempotent_write_js_1.deleteIdempotently)(context, key, (0, idempotent_write_js_1.revisionGuard)(rows_js_1.REVISION_ATTRIBUTE, observed));
34
+ return observed;
35
+ }
36
+ catch (error) {
37
+ const repinned = await repinOrResolve(context, key, error);
38
+ if (repinned === undefined)
39
+ return observed;
40
+ observed = repinned;
41
+ }
42
+ }
43
+ return undefined;
44
+ }
45
+ async function deleteStoreItem(context, address) {
46
+ const key = (0, rows_js_1.itemRowKey)(address);
47
+ const existing = await (0, rows_js_1.readExisting)(context, key);
48
+ const released = existing.exists ? await removeObservedRow(context, key, existing) : existing;
49
+ if (released === undefined) {
50
+ context.logger.warn('store.delete: compare-and-swap exhausted; the item was not deleted', {
51
+ namespace: address.namespace,
52
+ key: address.key,
53
+ attempts: idempotent_write_js_1.OVERWRITE_CAS_MAX_ATTEMPTS,
54
+ });
55
+ }
56
+ await (0, vector_index_js_1.dropVectorWhenGone)(context, address);
57
+ if (context.offloader && released?.value) {
58
+ await (0, offloader_js_1.cleanUpS3Orphans)(context.offloader, {
59
+ keys: (0, codec_js_1.collectS3Keys)([released.value]),
60
+ operation: 'store.delete',
61
+ logger: context.logger,
62
+ scope: [...address.namespace, address.key],
63
+ });
64
+ }
65
+ }
66
+ async function cleanUp(context, release, label, scope) {
67
+ if (!context.offloader || !release)
68
+ return;
69
+ await (0, offloader_js_1.cleanUpS3Orphans)(context.offloader, {
70
+ keys: (0, codec_js_1.collectS3Keys)([release]),
71
+ operation: label,
72
+ logger: context.logger,
73
+ ...(scope === undefined ? {} : { scope }),
74
+ });
75
+ }
76
+ function assertRowFits(record) {
77
+ const bytes = (0, row_size_js_1.rowSizeBytes)(record);
78
+ if (bytes <= row_size_js_1.MAX_ROW_BYTES)
79
+ return;
80
+ const { embeddings, ...bare } = record;
81
+ const vectorsOverflow = embeddings !== undefined && (0, row_size_js_1.rowSizeBytes)(bare) <= row_size_js_1.MAX_ROW_BYTES;
82
+ throw (0, errors_js_1.validationError)(vectorsOverflow
83
+ ? `the item's ${embeddings.length} inline vectors make its row ${bytes} bytes, over ` +
84
+ `DynamoDB's ${row_size_js_1.MAX_ROW_BYTES}-byte item limit; index fewer fields, embed with fewer ` +
85
+ 'dimensions, or configure a vectorBackend'
86
+ : `the item's row would be ${bytes} bytes, over DynamoDB's ${row_size_js_1.MAX_ROW_BYTES}-byte item ` +
87
+ 'limit; configure s3 offloading or store a smaller value', vectorsOverflow ? 'index' : 'value');
88
+ }
89
+ async function persistRow(context, record, existing) {
90
+ try {
91
+ assertRowFits(record);
92
+ }
93
+ catch (error) {
94
+ await cleanUp(context, record.value, 'store.put');
95
+ throw error;
96
+ }
97
+ let superseded;
98
+ if (context.offloader) {
99
+ const swap = await putWithRevisionSwap(context, record, existing);
100
+ superseded = swap.ok
101
+ ? swap.superseded
102
+ : await settleFailedPut(context, record, swap.reason, swap.pinned);
103
+ }
104
+ else {
105
+ try {
106
+ await (0, retry_js_1.withDynamoDBRetry)((request) => context.client.put({ TableName: context.tableName, Item: record }, request), context.retry);
107
+ superseded = existing;
108
+ }
109
+ catch (error) {
110
+ superseded = await settleFailedPut(context, record, error, existing);
111
+ }
112
+ }
113
+ await cleanUp(context, superseded.value, 'store.put.overwrite', [
114
+ ...record.namespace,
115
+ record.key,
116
+ ]);
117
+ }
118
+ async function settleFailedPut(context, record, error, pinned) {
119
+ const verdict = (0, idempotent_write_js_1.settledVerdict)(await verifyWriteLanded(context, record), error);
120
+ if (verdict === 'landed')
121
+ return pinned;
122
+ if (verdict === 'not-landed')
123
+ await cleanUp(context, record.value, 'store.put');
124
+ throw error;
125
+ }
126
+ async function put(context, record, observed) {
127
+ const guard = observed ? (0, idempotent_write_js_1.revisionGuard)(rows_js_1.REVISION_ATTRIBUTE, observed) : undefined;
128
+ await (0, idempotent_write_js_1.commitRow)(context, record, record.value, { guard });
129
+ }
130
+ async function putWithRevisionSwap(context, record, existing) {
131
+ let observed = existing;
132
+ for (let attempt = 1; attempt <= idempotent_write_js_1.OVERWRITE_CAS_MAX_ATTEMPTS; attempt++) {
133
+ const attempted = observed;
134
+ try {
135
+ await put(context, record, attempted);
136
+ return { ok: true, superseded: attempted };
137
+ }
138
+ catch (error) {
139
+ const rejection = error;
140
+ if (!(0, idempotent_write_js_1.isConditionalCheckFailed)(rejection)) {
141
+ return { ok: false, reason: rejection, pinned: attempted };
142
+ }
143
+ try {
144
+ const rejected = (0, idempotent_write_js_1.rejectedRow)(rejection);
145
+ observed = rejected
146
+ ? (0, rows_js_1.existingFrom)(rejected)
147
+ : await (0, rows_js_1.readExisting)(context, (0, table_schema_js_1.rowKeyOf)(record));
148
+ }
149
+ catch (readError) {
150
+ return { ok: false, reason: readError, pinned: attempted };
151
+ }
152
+ if (record.rev !== undefined && observed.revision === record.rev) {
153
+ return { ok: true, superseded: attempted };
154
+ }
155
+ record.createdAt = (0, rows_js_1.isLiveRow)(observed)
156
+ ? (observed.createdAt ?? record.createdAt)
157
+ : record.updatedAt;
158
+ }
159
+ }
160
+ context.logger.warn('store.put: compare-and-swap exhausted; overwriting unconditionally, which can orphan one ' +
161
+ 'S3 object under a concurrent put (reclaimed by ensureS3LifecycleRule)', { namespace: record.namespace, key: record.key, attempts: idempotent_write_js_1.OVERWRITE_CAS_MAX_ATTEMPTS });
162
+ try {
163
+ await put(context, record);
164
+ return { ok: true, superseded: observed };
165
+ }
166
+ catch (error) {
167
+ return { ok: false, reason: error, pinned: observed };
168
+ }
169
+ }
170
+ function isRetryExhausted(error) {
171
+ return (0, base_error_js_1.hasErrorCode)(error, error_code_js_1.ErrorCode.RETRY_EXHAUSTED);
172
+ }
173
+ async function verifyWriteLanded(context, record) {
174
+ const { verdict } = await (0, idempotent_write_js_1.verifyRow)(context, {
175
+ key: (0, table_schema_js_1.rowKeyOf)(record),
176
+ kind: 'attribute',
177
+ attribute: rows_js_1.REVISION_ATTRIBUTE,
178
+ expected: record.rev,
179
+ });
180
+ return verdict;
181
+ }
@@ -9,9 +9,9 @@
9
9
  * no later step checks again.
10
10
  */
11
11
  import type { BaseStore, ListNamespacesOperation, Operation, PutOperation, SearchOperation } from '@langchain/langgraph-checkpoint';
12
- import { type PageLimit } from '../../shared/validation/primitives';
13
- import type { ListNamespacesOptions } from '../types';
14
- import type { JsonValue } from './filter';
12
+ import { type PageLimit } from '../../shared/validation/primitives.js';
13
+ import type { ListNamespacesOptions } from '../types.js';
14
+ import type { JsonValue } from './filter.js';
15
15
  declare const namespaceBrand: unique symbol;
16
16
  declare const namespacePrefixBrand: unique symbol;
17
17
  declare const storeAddressBrand: unique symbol;
@@ -49,10 +49,12 @@ export type StoreAddress = {
49
49
  *
50
50
  * Returns: a copy of the labels, as a {@link NamespacePrefix}. A prefix no
51
51
  * stored namespace could ever match is refused rather than answered with a
52
- * silent empty page.
52
+ * silent empty page: a malformed label, or labels past the first that compose
53
+ * more sort key than DynamoDB allows a row to carry before any key — every
54
+ * label legal on its own, and still no item under it.
53
55
  *
54
- * Throws: `VALIDATION` naming `field` for a non-array, or `<field> element` for
55
- * a malformed label.
56
+ * Throws: `VALIDATION` naming `field` for a non-array or a path too wide for
57
+ * any sort key, or `<field> element` for a malformed label.
56
58
  */
57
59
  export declare function parseNamespacePrefix(value: unknown, field: string): NamespacePrefix;
58
60
  /**
@@ -169,13 +171,16 @@ export declare function parseListOperation(op: ListNamespacesOperation): ParsedL
169
171
  /**
170
172
  * Parse the options of `listNamespaces`.
171
173
  *
172
- * Accepts: `options` — only `prefix`, `suffix`, `maxDepth`, `limit` and
173
- * `offset`; `limit` defaults to 100 and `offset` to 0.
174
+ * Accepts: `options` — an object; `prefix`, `suffix`, `maxDepth`, `limit` and
175
+ * `offset` are read, `limit` defaulting to 100 and `offset` to 0. Any other key
176
+ * is ignored rather than refused: `BaseStore.listNamespaces` declares these
177
+ * options, so a key a later LangGraph adds must not refuse the call (decision
178
+ * record 28).
174
179
  *
175
180
  * Returns: the listing the options describe.
176
181
  *
177
- * Throws: `VALIDATION` naming `options.<key>` for a key this package does not
178
- * read, then as {@link parseListOperation}.
182
+ * Throws: `VALIDATION` naming `options` for options that are not an object,
183
+ * then as {@link parseListOperation}.
179
184
  */
180
185
  export declare function parseListNamespacesOptions(options: ListNamespacesOptions): ParsedList;
181
186
  /**
@@ -0,0 +1,180 @@
1
+ "use strict";
2
+ Object.defineProperty(exports, "__esModule", { value: true });
3
+ exports.parseNamespacePrefix = parseNamespacePrefix;
4
+ exports.parseNamespace = parseNamespace;
5
+ exports.parseStoreAddress = parseStoreAddress;
6
+ exports.parseSearch = parseSearch;
7
+ exports.parseListOperation = parseListOperation;
8
+ exports.parseListNamespacesOptions = parseListNamespacesOptions;
9
+ exports.parsePutArguments = parsePutArguments;
10
+ exports.parseOperation = parseOperation;
11
+ exports.parseOperations = parseOperations;
12
+ const table_schema_js_1 = require("../../shared/dynamodb/table-schema.js");
13
+ const errors_js_1 = require("../../shared/errors/errors.js");
14
+ const option_shape_js_1 = require("../../shared/validation/option-shape.js");
15
+ const primitives_js_1 = require("../../shared/validation/primitives.js");
16
+ const rows_js_1 = require("./rows.js");
17
+ const RESERVED_ROOT = 'langgraph';
18
+ const DEFAULT_SEARCH_LIMIT = (0, primitives_js_1.parseLimit)(10, 0);
19
+ const DEFAULT_LIST_LIMIT = 100;
20
+ function parseLabels(value, field) {
21
+ if (!Array.isArray(value)) {
22
+ throw (0, errors_js_1.validationError)(`${field} must be an array of labels`, field);
23
+ }
24
+ const labels = [];
25
+ for (const label of value) {
26
+ labels.push((0, primitives_js_1.parseIdentifier)(label, table_schema_js_1.KEY_SEPARATOR, `${field} element`, table_schema_js_1.MAX_KEY_SEGMENT_BYTES));
27
+ }
28
+ return labels;
29
+ }
30
+ function parseNamespacePrefix(value, field) {
31
+ const labels = parseLabels(value, field);
32
+ const bytes = Buffer.byteLength((0, rows_js_1.sortKeyPrefix)(labels), 'utf8');
33
+ if (bytes >= table_schema_js_1.MAX_SORT_KEY_BYTES) {
34
+ throw (0, errors_js_1.validationError)(`${field} leads a sort key with ${bytes} bytes before any key; DynamoDB caps sort keys at ` +
35
+ `${table_schema_js_1.MAX_SORT_KEY_BYTES} bytes, so no stored namespace can match it`, field);
36
+ }
37
+ return labels;
38
+ }
39
+ function parseNamespace(value, field = 'namespace') {
40
+ if (!Array.isArray(value) || value.length === 0) {
41
+ throw (0, errors_js_1.validationError)(`${field} must be a non-empty array`, field);
42
+ }
43
+ return parseLabels(value, field);
44
+ }
45
+ function parseStoreAddress(namespace, key) {
46
+ const parsedNamespace = parseNamespace(namespace);
47
+ const parsedKey = (0, primitives_js_1.parseIdentifier)(key, table_schema_js_1.KEY_SEPARATOR, 'key', table_schema_js_1.MAX_KEY_SEGMENT_BYTES);
48
+ const bytes = Buffer.byteLength((0, rows_js_1.sortKey)(parsedNamespace, parsedKey), 'utf8');
49
+ if (bytes > table_schema_js_1.MAX_SORT_KEY_BYTES) {
50
+ throw (0, errors_js_1.validationError)(`namespace and key compose a ${bytes}-byte sort key; DynamoDB caps sort keys at ` +
51
+ `${table_schema_js_1.MAX_SORT_KEY_BYTES} bytes`, 'sortKey');
52
+ }
53
+ return { namespace: parsedNamespace, key: parsedKey };
54
+ }
55
+ function parseIndex(index) {
56
+ if (index === undefined || index === false)
57
+ return index;
58
+ return (0, primitives_js_1.parseStringArray)(index, 'index');
59
+ }
60
+ function parseSearch(namespacePrefix, op) {
61
+ if (op.filter !== undefined)
62
+ (0, option_shape_js_1.assertObjectShape)(op.filter, 'filter');
63
+ const query = op.query === undefined ? undefined : (0, primitives_js_1.parseString)(op.query, 'query');
64
+ const offset = (0, primitives_js_1.parseInteger)(op.offset === undefined ? 0 : op.offset, 'offset', { min: 0 });
65
+ const limit = op.limit === undefined ? DEFAULT_SEARCH_LIMIT : (0, primitives_js_1.parseLimit)(op.limit, 0);
66
+ return {
67
+ kind: 'search',
68
+ namespacePrefix,
69
+ filter: op.filter,
70
+ query,
71
+ offset,
72
+ limit,
73
+ };
74
+ }
75
+ function parseMatchCondition(condition) {
76
+ (0, option_shape_js_1.assertObjectShape)(condition, 'matchConditions');
77
+ const { matchType, path } = condition;
78
+ if (matchType !== 'prefix' && matchType !== 'suffix') {
79
+ const received = typeof matchType === 'string' ? JSON.stringify(matchType) : typeof matchType;
80
+ throw (0, errors_js_1.validationError)(`matchType must be "prefix" or "suffix" (received ${received})`, 'matchConditions');
81
+ }
82
+ return { matchType, path: parseNamespacePrefix(path, matchType) };
83
+ }
84
+ function parseMatchConditions(conditions) {
85
+ if (conditions === undefined)
86
+ return undefined;
87
+ if (!Array.isArray(conditions)) {
88
+ throw (0, errors_js_1.validationError)('matchConditions must be an array', 'matchConditions');
89
+ }
90
+ const parsed = [];
91
+ for (const condition of conditions)
92
+ parsed.push(parseMatchCondition(condition));
93
+ return parsed;
94
+ }
95
+ function parseListOperation(op) {
96
+ const offset = (0, primitives_js_1.parseInteger)(op.offset, 'offset', { min: 0 });
97
+ const limit = (0, primitives_js_1.parseLimit)(op.limit, 0);
98
+ const maxDepth = op.maxDepth === undefined ? undefined : (0, primitives_js_1.parseInteger)(op.maxDepth, 'maxDepth', { min: 1 });
99
+ return {
100
+ kind: 'list',
101
+ matchConditions: parseMatchConditions(op.matchConditions),
102
+ maxDepth,
103
+ offset,
104
+ limit,
105
+ };
106
+ }
107
+ function parseListNamespacesOptions(options) {
108
+ (0, option_shape_js_1.assertObjectShape)(options, 'options');
109
+ const { prefix, suffix, maxDepth, limit = DEFAULT_LIST_LIMIT, offset = 0 } = options;
110
+ const matchConditions = [];
111
+ if (prefix !== undefined)
112
+ matchConditions.push({ matchType: 'prefix', path: prefix });
113
+ if (suffix !== undefined)
114
+ matchConditions.push({ matchType: 'suffix', path: suffix });
115
+ return parseListOperation({
116
+ matchConditions: matchConditions.length > 0 ? matchConditions : undefined,
117
+ maxDepth,
118
+ limit,
119
+ offset,
120
+ });
121
+ }
122
+ function assertNoPeriodLabel(namespace) {
123
+ if (namespace.some((label) => label.includes('.'))) {
124
+ throw (0, errors_js_1.validationError)('namespace element must not contain "."; upstream refuses it on every write', 'namespace element');
125
+ }
126
+ }
127
+ function assertUpstreamPutNamespace(namespace) {
128
+ assertNoPeriodLabel(namespace);
129
+ if (namespace[0] === RESERVED_ROOT) {
130
+ throw (0, errors_js_1.validationError)(`namespace must not start with "${RESERVED_ROOT}", the root label LangGraph reserves`, 'namespace');
131
+ }
132
+ }
133
+ function parsePutArguments(namespace, key, value, index) {
134
+ const address = parseStoreAddress(namespace, key);
135
+ assertUpstreamPutNamespace(address.namespace);
136
+ if (value === null) {
137
+ throw (0, errors_js_1.validationError)('value must be an object; delete() removes an item', 'value');
138
+ }
139
+ (0, option_shape_js_1.assertObjectShape)(value, 'value');
140
+ return {
141
+ kind: 'put',
142
+ address,
143
+ value: value,
144
+ index: parseIndex(index),
145
+ };
146
+ }
147
+ function parsePutOperation(op) {
148
+ const address = parseStoreAddress(op.namespace, op.key);
149
+ if (op.value !== null)
150
+ assertNoPeriodLabel(address.namespace);
151
+ if (op.value !== null)
152
+ (0, option_shape_js_1.assertObjectShape)(op.value, 'value');
153
+ const index = parseIndex(op.index);
154
+ if (op.value === null)
155
+ return { kind: 'delete', address };
156
+ return { kind: 'put', address, value: op.value, index };
157
+ }
158
+ function parseOperation(operation) {
159
+ if (typeof operation !== 'object' || operation === null || Array.isArray(operation)) {
160
+ throw (0, errors_js_1.validationError)('every operation in operations must be an object', 'operations');
161
+ }
162
+ if ('namespacePrefix' in operation) {
163
+ return parseSearch(parseNamespacePrefix(operation.namespacePrefix, 'namespacePrefix'), operation);
164
+ }
165
+ if ('value' in operation)
166
+ return parsePutOperation(operation);
167
+ if ('key' in operation) {
168
+ return { kind: 'get', address: parseStoreAddress(operation.namespace, operation.key) };
169
+ }
170
+ return parseListOperation(operation);
171
+ }
172
+ function parseOperations(operations) {
173
+ if (!Array.isArray(operations)) {
174
+ throw (0, errors_js_1.validationError)('operations must be an array', 'operations');
175
+ }
176
+ const parsed = [];
177
+ for (const operation of operations)
178
+ parsed.push(parseOperation(operation));
179
+ return parsed;
180
+ }
@@ -4,18 +4,16 @@
4
4
  * An item's namespace root is its partition and the rest of its namespace,
5
5
  * with its key, is its sort key, so a prefix search is a key-range query. How
6
6
  * those keys are composed, which attributes a row carries — its revision token,
7
- * timestamps, embeddings, recency-index keys — how a value is encoded into one
8
- * and decoded out, and which rows a read admits as this adapter's items are
9
- * decided here.
7
+ * timestamps, embeddings — how a value is encoded into one and decoded out,
8
+ * and which rows a read admits as this adapter's items are decided here.
10
9
  */
11
10
  import type { QueryCommandInput, ScanCommandInput } from '@aws-sdk/lib-dynamodb';
12
11
  import type { Item } from '@langchain/langgraph-checkpoint';
13
- import { type DescriptorRef, type PayloadDescriptor } from '../../shared/codec/codec';
14
- import type { AttributeMap } from '../../shared/dynamodb/client';
15
- import { type IndexTarget } from '../../shared/dynamodb/recency-index';
16
- import { type RowKey } from '../../shared/dynamodb/table-schema';
17
- import type { JsonValue } from './filter';
18
- import type { StoreContext } from './setup';
12
+ import { type DescriptorRef, type PayloadDescriptor } from '../../shared/codec/codec.js';
13
+ import type { AttributeMap } from '../../shared/dynamodb/client.js';
14
+ import { type RowKey } from '../../shared/dynamodb/table-schema.js';
15
+ import type { JsonValue } from './filter.js';
16
+ import type { StoreContext } from './setup.js';
19
17
  /**
20
18
  * The attribute an item row carries its revision token in, rewritten on every
21
19
  * put. A put's compare-and-swap and a delete's pin both hold the row to the
@@ -164,19 +162,38 @@ export declare function storeScan(tableName: string): ScanCommandInput;
164
162
  * transfer and unmarshalling, not cost.
165
163
  */
166
164
  export declare function projectKeys<T extends QueryCommandInput | ScanCommandInput>(params: T): T;
167
- /** The previous row's createdAt, payload descriptor and revision. */
165
+ /** The previous row's createdAt, expiry, payload descriptor and revision. */
168
166
  export interface ExistingRowMeta {
169
167
  exists: boolean;
170
168
  createdAt?: string;
169
+ /** The row's expiry stamp in epoch seconds, when it carries one. */
170
+ ttl?: number;
171
171
  value?: DescriptorRef;
172
172
  revision?: string;
173
173
  }
174
+ /**
175
+ * Whether a row a put is about to replace is an item to its readers.
176
+ *
177
+ * A row past its `ttl` is hidden from `get`, from every search and from every
178
+ * listing until DynamoDB's sweep removes it, which can lag for days; a put over
179
+ * one is a creation, not an update. The row's revision and descriptor still
180
+ * count — the swap must pin the row that is physically there and release the
181
+ * object it names — so this is asked only of what the put inherits.
182
+ *
183
+ * Accepts: `existing` — what {@link readExisting} or {@link existingFrom} read.
184
+ *
185
+ * Returns: true when there is a row and it has not expired.
186
+ *
187
+ * Throws: nothing.
188
+ */
189
+ export declare function isLiveRow(existing: ExistingRowMeta): boolean;
174
190
  /**
175
191
  * Read the fields a put needs from the row it is about to replace, in one
176
- * strongly-consistent projection: `createdAt` to preserve, the descriptor's
177
- * location and S3 key to clean up afterwards (never its inline bytes, which
178
- * can be hundreds of kilobytes the write would only discard), and the
179
- * revision the compare-and-swap pins.
192
+ * strongly-consistent projection: `createdAt` to preserve and the `ttl` that
193
+ * decides whether it is preserved, the descriptor's location and S3 key to
194
+ * clean up afterwards (never its inline bytes, which can be hundreds of
195
+ * kilobytes the write would only discard), and the revision the
196
+ * compare-and-swap pins.
180
197
  *
181
198
  * Lives apart from `actions/put.ts` so `item-write.ts` can re-read on a lost swap
182
199
  * without importing its own caller.
@@ -212,9 +229,6 @@ export interface StoreItemRow {
212
229
  SK: string;
213
230
  /** Row format version; absent on rows written before it existed (see `table-schema.ts`). */
214
231
  v?: number;
215
- /** Recency-index keys; absent on rows written before the index existed. */
216
- gsi1pk?: string;
217
- gsi1sk?: string;
218
232
  namespace: string[];
219
233
  key: string;
220
234
  value: PayloadDescriptor;
@@ -311,13 +325,15 @@ export interface BuildRowOptions {
311
325
  * reads back, and an offloaded value's key ends in; absent, a fresh UUID is
312
326
  * drawn, before the value is encoded.
313
327
  *
314
- * Returns: the complete row, including the recency-index attributes: a store
315
- * item is listed across partitions by a rootless search, so it is indexed.
328
+ * Returns: the complete row. It carries no recency-index keys: no store read
329
+ * uses that index.
316
330
  *
317
331
  * Throws: `VALIDATION` naming `value` for a value with no JSON
318
- * representation; `S3_OFFLOAD_FAILED` when an offloaded payload cannot be
319
- * uploaded. Encoding happens before any write, so a value that cannot be stored
320
- * never half-writes a row.
332
+ * representation, or `payload` for one too large to store inline without
333
+ * `s3`, or, once offloaded, larger than `s3.maxDownloadBytes`;
334
+ * `S3_OFFLOAD_FAILED` when an offloaded payload cannot be uploaded. Encoding
335
+ * happens before any write, so a value that cannot be stored never
336
+ * half-writes a row.
321
337
  */
322
338
  export declare function buildStoreRow(context: StoreContext, address: {
323
339
  namespace: string[];
@@ -341,15 +357,3 @@ export declare function buildStoreRow(context: StoreContext, address: {
341
357
  * overwrite.
342
358
  */
343
359
  export declare function readStoreItem(context: StoreContext, record: StoreItemRow, signal?: AbortSignal): Promise<Item>;
344
- /**
345
- * Where a store row sits in the recency index, for a row written before the
346
- * index existed.
347
- *
348
- * Accepts: `row` — any row of the table.
349
- *
350
- * Returns: an item row's identity — its sort key, at its own `updatedAt` — or
351
- * `undefined` for a row of another adapter.
352
- *
353
- * Throws: nothing.
354
- */
355
- export declare function storeIndexTarget(row: AttributeMap): IndexTarget | undefined;