@dimah-s3/react 1.7.0 → 2.0.0-beta.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 (148) hide show
  1. package/README.md +53 -13
  2. package/dist/api.d.ts +24 -15
  3. package/dist/api.d.ts.map +1 -1
  4. package/dist/chunk-SPUUNLXI.js +824 -0
  5. package/dist/chunk-SPUUNLXI.js.map +1 -0
  6. package/dist/create-s3-client.d.ts +1 -1
  7. package/dist/create-s3-client.d.ts.map +1 -1
  8. package/dist/engine.d.ts +15 -1
  9. package/dist/engine.d.ts.map +1 -1
  10. package/dist/engine.js +204 -512
  11. package/dist/engine.js.map +1 -1
  12. package/dist/helpers/format-accept-labels.d.ts +15 -2
  13. package/dist/helpers/format-accept-labels.d.ts.map +1 -1
  14. package/dist/helpers/format-date.d.ts +7 -0
  15. package/dist/helpers/format-date.d.ts.map +1 -0
  16. package/dist/helpers/format-dimah-error.d.ts +12 -2
  17. package/dist/helpers/format-dimah-error.d.ts.map +1 -1
  18. package/dist/helpers/format-file-size.d.ts +20 -0
  19. package/dist/helpers/format-file-size.d.ts.map +1 -0
  20. package/dist/helpers/format-speed.d.ts +1 -1
  21. package/dist/helpers/format-speed.d.ts.map +1 -1
  22. package/dist/helpers/format-upload-progress.d.ts +1 -1
  23. package/dist/helpers/format-upload-progress.d.ts.map +1 -1
  24. package/dist/helpers/index.d.ts +5 -8
  25. package/dist/helpers/index.d.ts.map +1 -1
  26. package/dist/helpers/load-route-catalog.d.ts +32 -8
  27. package/dist/helpers/load-route-catalog.d.ts.map +1 -1
  28. package/dist/helpers/throttled-speed.d.ts +2 -2
  29. package/dist/helpers/throttled-speed.d.ts.map +1 -1
  30. package/dist/helpers/to-timestamp.d.ts +5 -0
  31. package/dist/helpers/to-timestamp.d.ts.map +1 -0
  32. package/dist/helpers/truncate-file-name.d.ts +8 -0
  33. package/dist/helpers/truncate-file-name.d.ts.map +1 -0
  34. package/dist/helpers/use-format-accept-labels.d.ts +12 -0
  35. package/dist/helpers/use-format-accept-labels.d.ts.map +1 -0
  36. package/dist/helpers/use-format-eta.d.ts +14 -0
  37. package/dist/helpers/use-format-eta.d.ts.map +1 -0
  38. package/dist/helpers/use-format-speed.d.ts +12 -0
  39. package/dist/helpers/use-format-speed.d.ts.map +1 -0
  40. package/dist/hooks/use-delete.d.ts +6 -44
  41. package/dist/hooks/use-delete.d.ts.map +1 -1
  42. package/dist/hooks/use-download.d.ts +7 -117
  43. package/dist/hooks/use-download.d.ts.map +1 -1
  44. package/dist/hooks/use-fetch-download.d.ts +8 -0
  45. package/dist/hooks/use-fetch-download.d.ts.map +1 -0
  46. package/dist/hooks/use-file-intake.d.ts +43 -29
  47. package/dist/hooks/use-file-intake.d.ts.map +1 -1
  48. package/dist/hooks/use-file-upload.d.ts +38 -34
  49. package/dist/hooks/use-file-upload.d.ts.map +1 -1
  50. package/dist/hooks/use-object-list-selection.d.ts +78 -0
  51. package/dist/hooks/use-object-list-selection.d.ts.map +1 -0
  52. package/dist/hooks/use-object-list.d.ts +66 -16
  53. package/dist/hooks/use-object-list.d.ts.map +1 -1
  54. package/dist/hooks/use-object-url.d.ts +27 -10
  55. package/dist/hooks/use-object-url.d.ts.map +1 -1
  56. package/dist/hooks/use-route-upload-policy.d.ts +22 -14
  57. package/dist/hooks/use-route-upload-policy.d.ts.map +1 -1
  58. package/dist/hooks/use-upload.d.ts +72 -65
  59. package/dist/hooks/use-upload.d.ts.map +1 -1
  60. package/dist/index.d.ts +15 -19
  61. package/dist/index.d.ts.map +1 -1
  62. package/dist/index.js +2420 -2164
  63. package/dist/index.js.map +1 -1
  64. package/dist/internal/abortable.d.ts +9 -0
  65. package/dist/internal/abortable.d.ts.map +1 -0
  66. package/dist/internal/browser-download.d.ts +15 -0
  67. package/dist/internal/browser-download.d.ts.map +1 -0
  68. package/dist/internal/callbacks.d.ts +54 -0
  69. package/dist/internal/callbacks.d.ts.map +1 -0
  70. package/dist/internal/client-error.d.ts +15 -0
  71. package/dist/internal/client-error.d.ts.map +1 -0
  72. package/dist/internal/hooks.d.ts +27 -0
  73. package/dist/internal/hooks.d.ts.map +1 -0
  74. package/dist/internal/lru.d.ts +13 -0
  75. package/dist/internal/lru.d.ts.map +1 -0
  76. package/dist/internal/operations.d.ts +74 -0
  77. package/dist/internal/operations.d.ts.map +1 -0
  78. package/dist/internal/pool.d.ts +8 -0
  79. package/dist/internal/pool.d.ts.map +1 -0
  80. package/dist/list/entries.d.ts +14 -0
  81. package/dist/list/entries.d.ts.map +1 -0
  82. package/dist/list/memory-object-source.d.ts +60 -0
  83. package/dist/list/memory-object-source.d.ts.map +1 -0
  84. package/dist/list/types.d.ts +123 -11
  85. package/dist/list/types.d.ts.map +1 -1
  86. package/dist/s3-provider.d.ts +3 -2
  87. package/dist/s3-provider.d.ts.map +1 -1
  88. package/dist/store/local-storage-store.d.ts +5 -4
  89. package/dist/store/local-storage-store.d.ts.map +1 -1
  90. package/dist/store/memory-store.d.ts +3 -4
  91. package/dist/store/memory-store.d.ts.map +1 -1
  92. package/dist/translations/types.d.ts +105 -23
  93. package/dist/translations/types.d.ts.map +1 -1
  94. package/dist/types/delete.d.ts +98 -9
  95. package/dist/types/delete.d.ts.map +1 -1
  96. package/dist/types/download.d.ts +152 -23
  97. package/dist/types/download.d.ts.map +1 -1
  98. package/dist/types/index.d.ts +1 -1
  99. package/dist/types/index.d.ts.map +1 -1
  100. package/dist/types/operation.d.ts +38 -0
  101. package/dist/types/operation.d.ts.map +1 -0
  102. package/dist/types/upload-store.d.ts +30 -40
  103. package/dist/types/upload-store.d.ts.map +1 -1
  104. package/dist/types/upload.d.ts +177 -130
  105. package/dist/types/upload.d.ts.map +1 -1
  106. package/dist/upload/abort.d.ts +10 -0
  107. package/dist/upload/abort.d.ts.map +1 -0
  108. package/dist/upload/constants.d.ts +8 -3
  109. package/dist/upload/constants.d.ts.map +1 -1
  110. package/dist/upload/index.d.ts +3 -2
  111. package/dist/upload/index.d.ts.map +1 -1
  112. package/dist/upload/multipart.d.ts +14 -4
  113. package/dist/upload/multipart.d.ts.map +1 -1
  114. package/dist/upload/part-pool.d.ts +16 -0
  115. package/dist/upload/part-pool.d.ts.map +1 -0
  116. package/dist/upload/presigned-http.d.ts +5 -14
  117. package/dist/upload/presigned-http.d.ts.map +1 -1
  118. package/dist/upload/progress.d.ts +7 -0
  119. package/dist/upload/progress.d.ts.map +1 -0
  120. package/dist/upload/request.d.ts +9 -0
  121. package/dist/upload/request.d.ts.map +1 -0
  122. package/dist/upload/resume-key.d.ts +7 -3
  123. package/dist/upload/resume-key.d.ts.map +1 -1
  124. package/dist/upload/retry.d.ts +27 -2
  125. package/dist/upload/retry.d.ts.map +1 -1
  126. package/dist/upload/stored-upload.d.ts +7 -0
  127. package/dist/upload/stored-upload.d.ts.map +1 -0
  128. package/dist/upload/upload-file.d.ts +10 -11
  129. package/dist/upload/upload-file.d.ts.map +1 -1
  130. package/dist/upload/upload-part.d.ts +6 -3
  131. package/dist/upload/upload-part.d.ts.map +1 -1
  132. package/dist/upload/xhr-upload.d.ts +10 -2
  133. package/dist/upload/xhr-upload.d.ts.map +1 -1
  134. package/package.json +7 -8
  135. package/dist/helpers/format-eta.d.ts +0 -13
  136. package/dist/helpers/format-eta.d.ts.map +0 -1
  137. package/dist/helpers/format-validate-file-error.d.ts +0 -9
  138. package/dist/helpers/format-validate-file-error.d.ts.map +0 -1
  139. package/dist/hooks/index.d.ts +0 -7
  140. package/dist/hooks/index.d.ts.map +0 -1
  141. package/dist/internal-helpers.d.ts +0 -10
  142. package/dist/internal-helpers.d.ts.map +0 -1
  143. package/dist/store/use-immer-state.d.ts +0 -8
  144. package/dist/store/use-immer-state.d.ts.map +0 -1
  145. package/dist/types/error.d.ts +0 -27
  146. package/dist/types/error.d.ts.map +0 -1
  147. package/dist/upload/upload-files.d.ts +0 -26
  148. package/dist/upload/upload-files.d.ts.map +0 -1
package/README.md CHANGED
@@ -1,35 +1,75 @@
1
1
  # @dimah-s3/react
2
2
 
3
+ **2.0 beta.** Install with `@beta`. `@latest` stays on 1.x, and betas can include breaking changes until 2.0.0.
4
+
3
5
  Headless React hooks for S3 upload, download, and delete flows.
4
6
 
5
- Full documentation: [s3.dimah.dev/docs/react](https://s3.dimah.dev/docs/react) ·
6
- [llms.txt](https://s3.dimah.dev/llms.txt)
7
+ Full documentation: [v2.s3.dimah.dev/docs/react](https://v2.s3.dimah.dev/docs/react) ·
8
+ [llms.txt](https://v2.s3.dimah.dev/llms.txt)
7
9
 
8
10
  ## Install
9
11
 
10
12
  ```bash
11
- pnpm add @dimah-s3/react
13
+ pnpm add @dimah-s3/react@beta @dimah-s3/core@beta @fuma-translate/react
12
14
  ```
13
15
 
16
+ Requires React 19.2.
17
+
14
18
  ## Minimal setup
15
19
 
20
+ Create the client once, in a client module:
21
+
16
22
  ```tsx
17
- import { createS3Client, useUpload } from "@dimah-s3/react";
23
+ "use client";
24
+
25
+ import { createS3Client } from "@dimah-s3/react";
18
26
 
19
27
  export const s3Client = createS3Client();
28
+ ```
29
+
30
+ Wrap your app in `<s3Client.Provider>`. Then call a hook with a route name.
31
+ The server builds the object key:
20
32
 
21
- // App root
22
- <s3Client.Provider>{children}</s3Client.Provider>;
33
+ ```tsx
34
+ "use client";
35
+
36
+ import { useUpload } from "@dimah-s3/react";
37
+
38
+ export function AvatarPicker() {
39
+ const upload = useUpload({ route: "avatar", accept: ["image/*"] });
23
40
 
24
- // In a component
25
- const { open, getInputProps } = useUpload({
26
- route: "uploads",
27
- noDrag: true,
28
- noClick: true,
29
- noKeyboard: true,
30
- });
41
+ return (
42
+ <>
43
+ <input {...upload.getInputProps()} />
44
+ <button
45
+ type="button"
46
+ disabled={upload.isPending}
47
+ onClick={() => upload.open()}
48
+ >
49
+ {upload.isPending
50
+ ? `Uploading ${upload.progress.percent}%`
51
+ : "Upload avatar"}
52
+ </button>
53
+ {upload.error ? <p role="alert">{upload.error.message}</p> : null}
54
+ </>
55
+ );
56
+ }
31
57
  ```
32
58
 
59
+ ## Entries
60
+
61
+ - `@dimah-s3/react`: the hooks (`useUpload`, `useDownload`,
62
+ `useFetchDownload`, `useDelete`, `useObjectUrl`, `useObjectList`, …),
63
+ `S3Provider`, `createS3Client`, and the types. It is a `"use client"`
64
+ module.
65
+ - `@dimah-s3/react/engine`: plain functions with no React import, such as
66
+ `uploadFile`, `memoryObjectSource`, `defineApi`, `loadRouteCatalog`, and
67
+ `createLocalStorageStore`. Shared and server modules can import it.
68
+ - `APIError`, `S3_ERROR_CODES`, and the other protocol helpers come from
69
+ `@dimah-s3/core`.
70
+
71
+ For prebuilt components, see [`@dimah-s3/ui`](https://v2.s3.dimah.dev/docs/react/ui).
72
+
33
73
  ## License
34
74
 
35
75
  MIT
package/dist/api.d.ts CHANGED
@@ -1,29 +1,38 @@
1
+ import type { S3Api } from "@dimah-s3/core";
2
+ import type { S3ApiUploadTransport } from "./types/upload";
1
3
  /**
2
- * Type helper for a custom dimah-s3 presign API.
4
+ * Type helper for a custom dimah-s3 API.
3
5
  *
4
- * Accepts an `S3Api` object — implement each method to call your own backend
5
- * endpoint, tRPC mutation, GraphQL query, or anything else. The object is
6
- * returned as-is; `defineApi` just enforces the type contract.
6
+ * Implement each `S3Api` method to call your own backend endpoint, tRPC
7
+ * mutation, GraphQL query, or anything else. Each method takes
8
+ * `(payload, options)`; forward `options.signal` so cancels reach the
9
+ * request. Add `uploadTransport` to replace the byte transfer. The object is
10
+ * returned as-is; `defineApi` only checks the type.
7
11
  *
8
- * If you are using the default dimah-s3 route layout, use `createS3Client`
9
- * from `@dimah-s3/react` (or `@dimah-s3/core` without React bindings).
12
+ * With the default dimah-s3 route layout, use `createS3Client` from
13
+ * `@dimah-s3/react` (or `@dimah-s3/core` without React bindings) instead.
10
14
  *
11
15
  * @example
12
16
  * ```ts
13
- * import { defineApi } from "@dimah-s3/react";
17
+ * import { defineApi } from "@dimah-s3/react/engine";
14
18
  *
15
19
  * export const api = defineApi({
16
- * async upload(payload) {
17
- * return fetch("/api/storage/presign", { method: "POST", body: JSON.stringify(payload) })
18
- * .then(r => r.json());
20
+ * async upload(payload, options) {
21
+ * const res = await fetch("/api/storage/presign", {
22
+ * method: "POST",
23
+ * body: JSON.stringify(payload),
24
+ * signal: options?.signal,
25
+ * });
26
+ * return res.json();
19
27
  * },
20
- * async confirm(payload) { ... },
21
- * async download(payload) { ... },
22
- * async delete(payload) { ... },
28
+ * async confirm(payload, options) { ... },
29
+ * async download(payload, options) { ... },
30
+ * async catalog(options) { ... },
31
+ * async delete(payload, options) { ... },
32
+ * async deleteMany(payload, options) { ... },
23
33
  * multipart: { init, signPart, listParts, complete, abort },
24
34
  * });
25
35
  * ```
26
36
  */
27
- import type { S3Api } from "@dimah-s3/core";
28
- export declare function defineApi(input: S3Api): S3Api;
37
+ export declare function defineApi<TApi extends S3Api & S3ApiUploadTransport>(api: TApi): TApi;
29
38
  //# sourceMappingURL=api.d.ts.map
package/dist/api.d.ts.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;GAyBG;AACH,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAE5C,wBAAgB,SAAS,CAAC,KAAK,EAAE,KAAK,GAAG,KAAK,CAE7C"}
1
+ {"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../src/api.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,gBAAgB,CAAC;AAC5C,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC;AAE3D;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAiCG;AACH,wBAAgB,SAAS,CAAC,IAAI,SAAS,KAAK,GAAG,oBAAoB,EACjE,GAAG,EAAE,IAAI,GACR,IAAI,CAEN"}