@geekmidas/storage 10.0.0-alpha.15 → 10.0.0-alpha.151

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 (44) hide show
  1. package/README.md +49 -13
  2. package/dist/aws.cjs +88 -10
  3. package/dist/aws.cjs.map +1 -1
  4. package/dist/aws.d.cts +5 -2
  5. package/dist/aws.d.cts.map +1 -1
  6. package/dist/aws.d.mts +5 -2
  7. package/dist/aws.d.mts.map +1 -1
  8. package/dist/aws.mjs +88 -10
  9. package/dist/aws.mjs.map +1 -1
  10. package/dist/{errors-Bexjg-j-.cjs → errors-BB8jdHif.cjs} +52 -3
  11. package/dist/errors-BB8jdHif.cjs.map +1 -0
  12. package/dist/{errors-CpYcpJCY.mjs → errors-COXs1iNg.mjs} +41 -4
  13. package/dist/errors-COXs1iNg.mjs.map +1 -0
  14. package/dist/events.cjs +98 -0
  15. package/dist/events.cjs.map +1 -0
  16. package/dist/events.d.cts +58 -0
  17. package/dist/events.d.cts.map +1 -0
  18. package/dist/events.d.mts +58 -0
  19. package/dist/events.d.mts.map +1 -0
  20. package/dist/events.mjs +94 -0
  21. package/dist/events.mjs.map +1 -0
  22. package/dist/index.cjs +3 -1
  23. package/dist/index.d.cts +27 -3
  24. package/dist/index.d.cts.map +1 -1
  25. package/dist/index.d.mts +27 -3
  26. package/dist/index.d.mts.map +1 -1
  27. package/dist/index.mjs +2 -2
  28. package/dist/{registry-ClEvHGpM.d.cts → registry-DyBOtv6n.d.cts} +44 -2
  29. package/dist/registry-DyBOtv6n.d.cts.map +1 -0
  30. package/dist/{registry-ClEvHGpM.d.mts → registry-DyBOtv6n.d.mts} +44 -2
  31. package/dist/registry-DyBOtv6n.d.mts.map +1 -0
  32. package/dist/s3Url.cjs +37 -8
  33. package/dist/s3Url.cjs.map +1 -1
  34. package/dist/s3Url.d.cts +20 -6
  35. package/dist/s3Url.d.cts.map +1 -1
  36. package/dist/s3Url.d.mts +20 -6
  37. package/dist/s3Url.d.mts.map +1 -1
  38. package/dist/s3Url.mjs +37 -8
  39. package/dist/s3Url.mjs.map +1 -1
  40. package/package.json +20 -5
  41. package/dist/errors-Bexjg-j-.cjs.map +0 -1
  42. package/dist/errors-CpYcpJCY.mjs.map +0 -1
  43. package/dist/registry-ClEvHGpM.d.cts.map +0 -1
  44. package/dist/registry-ClEvHGpM.d.mts.map +0 -1
@@ -13,14 +13,37 @@
13
13
  */
14
14
  /** Base for anything wrong with a storage URL, so callers may catch broadly. */
15
15
  var StorageUrlError = class extends Error {
16
- /** The URL that could not be used. */
16
+ /**
17
+ * The URL that could not be used, with any credentials it carried replaced
18
+ * by `REDACTED` — an error is logged, and a key in its userinfo would be
19
+ * logged with it.
20
+ */
17
21
  url;
18
22
  constructor(url, message) {
19
23
  super(message);
20
- this.url = url;
24
+ this.url = redactStorageUrl(url);
21
25
  this.name = new.target.name;
22
26
  }
23
27
  };
28
+ /**
29
+ * Replace a URL's userinfo with `REDACTED`, so `s3://KEY:SECRET@uploads` can be
30
+ * logged as `s3://REDACTED@uploads`. A URL without userinfo comes back as is.
31
+ *
32
+ * A string the URL parser rejects is still redacted, up to its last `@`: an
33
+ * unencoded `/` in a secret is the commonest way to write a malformed one, and
34
+ * that string is exactly the one that ends up in an error.
35
+ */
36
+ function redactStorageUrl(url) {
37
+ try {
38
+ const parsed = new URL(url);
39
+ if (!parsed.username && !parsed.password) return url;
40
+ parsed.username = "REDACTED";
41
+ parsed.password = "";
42
+ return parsed.toString();
43
+ } catch {
44
+ return url.replace(/^([a-z][a-z0-9+.-]*:\/\/).*@/i, "$1REDACTED@");
45
+ }
46
+ }
24
47
  /** The string is not a URL at all. */
25
48
  var MalformedStorageUrl = class extends StorageUrlError {
26
49
  constructor(url) {
@@ -56,6 +79,20 @@ var MissingStorageBucket = class extends StorageUrlError {
56
79
  }
57
80
  };
58
81
  /**
82
+ * The URL's userinfo carries one half of a key pair: an access key with no
83
+ * secret, or a secret with no access key. Either both are in the URL, or
84
+ * neither is and the provider's default credential chain applies — half a pair
85
+ * is never silently completed from the environment.
86
+ */
87
+ var IncompleteStorageCredentials = class extends StorageUrlError {
88
+ /** Which half is missing: `'accessKeyId'` or `'secretAccessKey'`. */
89
+ missing;
90
+ constructor(url, missing) {
91
+ super(url, "Storage URL credentials need both halves: write them as KEY:SECRET@bucket, or leave them out to use the default credential chain");
92
+ this.missing = missing;
93
+ }
94
+ };
95
+ /**
59
96
  * No driver is registered for the URL's scheme.
60
97
  *
61
98
  * Usually means the build pinned a driver for a different target, or an entry
@@ -74,6 +111,12 @@ var UnregisteredStorageScheme = class extends StorageUrlError {
74
111
  }
75
112
  };
76
113
  //#endregion
114
+ Object.defineProperty(exports, "IncompleteStorageCredentials", {
115
+ enumerable: true,
116
+ get: function() {
117
+ return IncompleteStorageCredentials;
118
+ }
119
+ });
77
120
  Object.defineProperty(exports, "MalformedStorageUrl", {
78
121
  enumerable: true,
79
122
  get: function() {
@@ -104,5 +147,11 @@ Object.defineProperty(exports, "UnregisteredStorageScheme", {
104
147
  return UnregisteredStorageScheme;
105
148
  }
106
149
  });
150
+ Object.defineProperty(exports, "redactStorageUrl", {
151
+ enumerable: true,
152
+ get: function() {
153
+ return redactStorageUrl;
154
+ }
155
+ });
107
156
 
108
- //# sourceMappingURL=errors-Bexjg-j-.cjs.map
157
+ //# sourceMappingURL=errors-BB8jdHif.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors-BB8jdHif.cjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Storage errors — shared by every implementation, not just S3.\n *\n * A `gs://` or Azure client hits the same three problems as the S3 one: the\n * string is not a URL, it is a URL for a different provider, or it addresses no\n * bucket. Each carries the provider-specific detail as a field, so the type is\n * common while the specifics stay accurate.\n *\n * Messages state the rule, which is constant, and never interpolate the value.\n * An interpolated message cannot be matched on, reads differently every time it\n * is thrown, and carries user input into every log line that touches it.\n */\n\n/** Base for anything wrong with a storage URL, so callers may catch broadly. */\nexport abstract class StorageUrlError extends Error {\n\t/**\n\t * The URL that could not be used, with any credentials it carried replaced\n\t * by `REDACTED` — an error is logged, and a key in its userinfo would be\n\t * logged with it.\n\t */\n\treadonly url: string;\n\n\tconstructor(url: string, message: string) {\n\t\tsuper(message);\n\t\tthis.url = redactStorageUrl(url);\n\t\tthis.name = new.target.name;\n\t}\n}\n\n/**\n * Replace a URL's userinfo with `REDACTED`, so `s3://KEY:SECRET@uploads` can be\n * logged as `s3://REDACTED@uploads`. A URL without userinfo comes back as is.\n *\n * A string the URL parser rejects is still redacted, up to its last `@`: an\n * unencoded `/` in a secret is the commonest way to write a malformed one, and\n * that string is exactly the one that ends up in an error.\n */\nexport function redactStorageUrl(url: string): string {\n\ttry {\n\t\tconst parsed = new URL(url);\n\t\tif (!parsed.username && !parsed.password) return url;\n\t\tparsed.username = 'REDACTED';\n\t\tparsed.password = '';\n\t\treturn parsed.toString();\n\t} catch {\n\t\treturn url.replace(/^([a-z][a-z0-9+.-]*:\\/\\/).*@/i, '$1REDACTED@');\n\t}\n}\n\n/** The string is not a URL at all. */\nexport class MalformedStorageUrl extends StorageUrlError {\n\tconstructor(url: string) {\n\t\tsuper(url, 'Not a valid URL');\n\t}\n}\n\n/**\n * A URL, but for a different provider — a `gs://` URL reaching the S3 client,\n * or the reverse. The usual cause is a construct resolving against the wrong\n * target, which is worth distinguishing from a malformed string.\n */\nexport class UnexpectedStorageScheme extends StorageUrlError {\n\t/** The scheme this client handles, e.g. `'s3:'`. */\n\treadonly expected: string;\n\t/** The scheme the URL actually carried, e.g. `'gs:'`. */\n\treadonly actual: string;\n\n\tconstructor(url: string, expected: string, actual: string) {\n\t\tsuper(url, 'Storage URL is for a different provider');\n\t\tthis.expected = expected;\n\t\tthis.actual = actual;\n\t}\n}\n\n/**\n * A well-formed URL that addresses no bucket.\n *\n * \"Bucket\" is the term S3 and GCS share; Azure calls the same thing a\n * container. One error covers all three — the word in the message is the\n * common one rather than a new abstraction nobody uses.\n */\nexport class MissingStorageBucket extends StorageUrlError {\n\tconstructor(url: string) {\n\t\tsuper(url, 'Storage URL must address a bucket');\n\t}\n}\n\n/**\n * The URL's userinfo carries one half of a key pair: an access key with no\n * secret, or a secret with no access key. Either both are in the URL, or\n * neither is and the provider's default credential chain applies — half a pair\n * is never silently completed from the environment.\n */\nexport class IncompleteStorageCredentials extends StorageUrlError {\n\t/** Which half is missing: `'accessKeyId'` or `'secretAccessKey'`. */\n\treadonly missing: 'accessKeyId' | 'secretAccessKey';\n\n\tconstructor(url: string, missing: 'accessKeyId' | 'secretAccessKey') {\n\t\tsuper(\n\t\t\turl,\n\t\t\t'Storage URL credentials need both halves: write them as KEY:SECRET@bucket, or leave them out to use the default credential chain',\n\t\t);\n\t\tthis.missing = missing;\n\t}\n}\n\n/**\n * No driver is registered for the URL's scheme.\n *\n * Usually means the build pinned a driver for a different target, or an entry\n * point registered nothing at all — so the registered schemes are carried\n * alongside, since \"what *is* available\" is the actionable half.\n */\nexport class UnregisteredStorageScheme extends StorageUrlError {\n\t/** The scheme that had no driver, e.g. `'gs:'`. */\n\treadonly scheme: string;\n\t/** What is registered, so the caller can see what was pinned instead. */\n\treadonly registered: readonly string[];\n\n\tconstructor(url: string, scheme: string, registered: readonly string[]) {\n\t\tsuper(url, 'No storage driver is registered for this URL scheme');\n\t\tthis.scheme = scheme;\n\t\tthis.registered = registered;\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;AAcA,IAAsB,kBAAtB,cAA8C,MAAM;;;;;;CAMnD;CAEA,YAAY,KAAa,SAAiB;EACzC,MAAM,OAAO;EACb,KAAK,MAAM,iBAAiB,GAAG;EAC/B,KAAK,OAAO,WAAW;CACxB;AACD;;;;;;;;;AAUA,SAAgB,iBAAiB,KAAqB;CACrD,IAAI;EACH,MAAM,SAAS,IAAI,IAAI,GAAG;EAC1B,IAAI,CAAC,OAAO,YAAY,CAAC,OAAO,UAAU,OAAO;EACjD,OAAO,WAAW;EAClB,OAAO,WAAW;EAClB,OAAO,OAAO,SAAS;CACxB,QAAQ;EACP,OAAO,IAAI,QAAQ,iCAAiC,aAAa;CAClE;AACD;;AAGA,IAAa,sBAAb,cAAyC,gBAAgB;CACxD,YAAY,KAAa;EACxB,MAAM,KAAK,iBAAiB;CAC7B;AACD;;;;;;AAOA,IAAa,0BAAb,cAA6C,gBAAgB;;CAE5D;;CAEA;CAEA,YAAY,KAAa,UAAkB,QAAgB;EAC1D,MAAM,KAAK,yCAAyC;EACpD,KAAK,WAAW;EAChB,KAAK,SAAS;CACf;AACD;;;;;;;;AASA,IAAa,uBAAb,cAA0C,gBAAgB;CACzD,YAAY,KAAa;EACxB,MAAM,KAAK,mCAAmC;CAC/C;AACD;;;;;;;AAQA,IAAa,+BAAb,cAAkD,gBAAgB;;CAEjE;CAEA,YAAY,KAAa,SAA4C;EACpE,MACC,KACA,kIACD;EACA,KAAK,UAAU;CAChB;AACD;;;;;;;;AASA,IAAa,4BAAb,cAA+C,gBAAgB;;CAE9D;;CAEA;CAEA,YAAY,KAAa,QAAgB,YAA+B;EACvE,MAAM,KAAK,qDAAqD;EAChE,KAAK,SAAS;EACd,KAAK,aAAa;CACnB;AACD"}
@@ -13,14 +13,37 @@
13
13
  */
14
14
  /** Base for anything wrong with a storage URL, so callers may catch broadly. */
15
15
  var StorageUrlError = class extends Error {
16
- /** The URL that could not be used. */
16
+ /**
17
+ * The URL that could not be used, with any credentials it carried replaced
18
+ * by `REDACTED` — an error is logged, and a key in its userinfo would be
19
+ * logged with it.
20
+ */
17
21
  url;
18
22
  constructor(url, message) {
19
23
  super(message);
20
- this.url = url;
24
+ this.url = redactStorageUrl(url);
21
25
  this.name = new.target.name;
22
26
  }
23
27
  };
28
+ /**
29
+ * Replace a URL's userinfo with `REDACTED`, so `s3://KEY:SECRET@uploads` can be
30
+ * logged as `s3://REDACTED@uploads`. A URL without userinfo comes back as is.
31
+ *
32
+ * A string the URL parser rejects is still redacted, up to its last `@`: an
33
+ * unencoded `/` in a secret is the commonest way to write a malformed one, and
34
+ * that string is exactly the one that ends up in an error.
35
+ */
36
+ function redactStorageUrl(url) {
37
+ try {
38
+ const parsed = new URL(url);
39
+ if (!parsed.username && !parsed.password) return url;
40
+ parsed.username = "REDACTED";
41
+ parsed.password = "";
42
+ return parsed.toString();
43
+ } catch {
44
+ return url.replace(/^([a-z][a-z0-9+.-]*:\/\/).*@/i, "$1REDACTED@");
45
+ }
46
+ }
24
47
  /** The string is not a URL at all. */
25
48
  var MalformedStorageUrl = class extends StorageUrlError {
26
49
  constructor(url) {
@@ -56,6 +79,20 @@ var MissingStorageBucket = class extends StorageUrlError {
56
79
  }
57
80
  };
58
81
  /**
82
+ * The URL's userinfo carries one half of a key pair: an access key with no
83
+ * secret, or a secret with no access key. Either both are in the URL, or
84
+ * neither is and the provider's default credential chain applies — half a pair
85
+ * is never silently completed from the environment.
86
+ */
87
+ var IncompleteStorageCredentials = class extends StorageUrlError {
88
+ /** Which half is missing: `'accessKeyId'` or `'secretAccessKey'`. */
89
+ missing;
90
+ constructor(url, missing) {
91
+ super(url, "Storage URL credentials need both halves: write them as KEY:SECRET@bucket, or leave them out to use the default credential chain");
92
+ this.missing = missing;
93
+ }
94
+ };
95
+ /**
59
96
  * No driver is registered for the URL's scheme.
60
97
  *
61
98
  * Usually means the build pinned a driver for a different target, or an entry
@@ -74,6 +111,6 @@ var UnregisteredStorageScheme = class extends StorageUrlError {
74
111
  }
75
112
  };
76
113
  //#endregion
77
- export { UnregisteredStorageScheme as a, UnexpectedStorageScheme as i, MissingStorageBucket as n, StorageUrlError as r, MalformedStorageUrl as t };
114
+ export { UnexpectedStorageScheme as a, StorageUrlError as i, MalformedStorageUrl as n, UnregisteredStorageScheme as o, MissingStorageBucket as r, redactStorageUrl as s, IncompleteStorageCredentials as t };
78
115
 
79
- //# sourceMappingURL=errors-CpYcpJCY.mjs.map
116
+ //# sourceMappingURL=errors-COXs1iNg.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"errors-COXs1iNg.mjs","names":[],"sources":["../src/errors.ts"],"sourcesContent":["/**\n * Storage errors — shared by every implementation, not just S3.\n *\n * A `gs://` or Azure client hits the same three problems as the S3 one: the\n * string is not a URL, it is a URL for a different provider, or it addresses no\n * bucket. Each carries the provider-specific detail as a field, so the type is\n * common while the specifics stay accurate.\n *\n * Messages state the rule, which is constant, and never interpolate the value.\n * An interpolated message cannot be matched on, reads differently every time it\n * is thrown, and carries user input into every log line that touches it.\n */\n\n/** Base for anything wrong with a storage URL, so callers may catch broadly. */\nexport abstract class StorageUrlError extends Error {\n\t/**\n\t * The URL that could not be used, with any credentials it carried replaced\n\t * by `REDACTED` — an error is logged, and a key in its userinfo would be\n\t * logged with it.\n\t */\n\treadonly url: string;\n\n\tconstructor(url: string, message: string) {\n\t\tsuper(message);\n\t\tthis.url = redactStorageUrl(url);\n\t\tthis.name = new.target.name;\n\t}\n}\n\n/**\n * Replace a URL's userinfo with `REDACTED`, so `s3://KEY:SECRET@uploads` can be\n * logged as `s3://REDACTED@uploads`. A URL without userinfo comes back as is.\n *\n * A string the URL parser rejects is still redacted, up to its last `@`: an\n * unencoded `/` in a secret is the commonest way to write a malformed one, and\n * that string is exactly the one that ends up in an error.\n */\nexport function redactStorageUrl(url: string): string {\n\ttry {\n\t\tconst parsed = new URL(url);\n\t\tif (!parsed.username && !parsed.password) return url;\n\t\tparsed.username = 'REDACTED';\n\t\tparsed.password = '';\n\t\treturn parsed.toString();\n\t} catch {\n\t\treturn url.replace(/^([a-z][a-z0-9+.-]*:\\/\\/).*@/i, '$1REDACTED@');\n\t}\n}\n\n/** The string is not a URL at all. */\nexport class MalformedStorageUrl extends StorageUrlError {\n\tconstructor(url: string) {\n\t\tsuper(url, 'Not a valid URL');\n\t}\n}\n\n/**\n * A URL, but for a different provider — a `gs://` URL reaching the S3 client,\n * or the reverse. The usual cause is a construct resolving against the wrong\n * target, which is worth distinguishing from a malformed string.\n */\nexport class UnexpectedStorageScheme extends StorageUrlError {\n\t/** The scheme this client handles, e.g. `'s3:'`. */\n\treadonly expected: string;\n\t/** The scheme the URL actually carried, e.g. `'gs:'`. */\n\treadonly actual: string;\n\n\tconstructor(url: string, expected: string, actual: string) {\n\t\tsuper(url, 'Storage URL is for a different provider');\n\t\tthis.expected = expected;\n\t\tthis.actual = actual;\n\t}\n}\n\n/**\n * A well-formed URL that addresses no bucket.\n *\n * \"Bucket\" is the term S3 and GCS share; Azure calls the same thing a\n * container. One error covers all three — the word in the message is the\n * common one rather than a new abstraction nobody uses.\n */\nexport class MissingStorageBucket extends StorageUrlError {\n\tconstructor(url: string) {\n\t\tsuper(url, 'Storage URL must address a bucket');\n\t}\n}\n\n/**\n * The URL's userinfo carries one half of a key pair: an access key with no\n * secret, or a secret with no access key. Either both are in the URL, or\n * neither is and the provider's default credential chain applies — half a pair\n * is never silently completed from the environment.\n */\nexport class IncompleteStorageCredentials extends StorageUrlError {\n\t/** Which half is missing: `'accessKeyId'` or `'secretAccessKey'`. */\n\treadonly missing: 'accessKeyId' | 'secretAccessKey';\n\n\tconstructor(url: string, missing: 'accessKeyId' | 'secretAccessKey') {\n\t\tsuper(\n\t\t\turl,\n\t\t\t'Storage URL credentials need both halves: write them as KEY:SECRET@bucket, or leave them out to use the default credential chain',\n\t\t);\n\t\tthis.missing = missing;\n\t}\n}\n\n/**\n * No driver is registered for the URL's scheme.\n *\n * Usually means the build pinned a driver for a different target, or an entry\n * point registered nothing at all — so the registered schemes are carried\n * alongside, since \"what *is* available\" is the actionable half.\n */\nexport class UnregisteredStorageScheme extends StorageUrlError {\n\t/** The scheme that had no driver, e.g. `'gs:'`. */\n\treadonly scheme: string;\n\t/** What is registered, so the caller can see what was pinned instead. */\n\treadonly registered: readonly string[];\n\n\tconstructor(url: string, scheme: string, registered: readonly string[]) {\n\t\tsuper(url, 'No storage driver is registered for this URL scheme');\n\t\tthis.scheme = scheme;\n\t\tthis.registered = registered;\n\t}\n}\n"],"mappings":";;;;;;;;;;;;;;AAcA,IAAsB,kBAAtB,cAA8C,MAAM;;;;;;CAMnD;CAEA,YAAY,KAAa,SAAiB;EACzC,MAAM,OAAO;EACb,KAAK,MAAM,iBAAiB,GAAG;EAC/B,KAAK,OAAO,WAAW;CACxB;AACD;;;;;;;;;AAUA,SAAgB,iBAAiB,KAAqB;CACrD,IAAI;EACH,MAAM,SAAS,IAAI,IAAI,GAAG;EAC1B,IAAI,CAAC,OAAO,YAAY,CAAC,OAAO,UAAU,OAAO;EACjD,OAAO,WAAW;EAClB,OAAO,WAAW;EAClB,OAAO,OAAO,SAAS;CACxB,QAAQ;EACP,OAAO,IAAI,QAAQ,iCAAiC,aAAa;CAClE;AACD;;AAGA,IAAa,sBAAb,cAAyC,gBAAgB;CACxD,YAAY,KAAa;EACxB,MAAM,KAAK,iBAAiB;CAC7B;AACD;;;;;;AAOA,IAAa,0BAAb,cAA6C,gBAAgB;;CAE5D;;CAEA;CAEA,YAAY,KAAa,UAAkB,QAAgB;EAC1D,MAAM,KAAK,yCAAyC;EACpD,KAAK,WAAW;EAChB,KAAK,SAAS;CACf;AACD;;;;;;;;AASA,IAAa,uBAAb,cAA0C,gBAAgB;CACzD,YAAY,KAAa;EACxB,MAAM,KAAK,mCAAmC;CAC/C;AACD;;;;;;;AAQA,IAAa,+BAAb,cAAkD,gBAAgB;;CAEjE;CAEA,YAAY,KAAa,SAA4C;EACpE,MACC,KACA,kIACD;EACA,KAAK,UAAU;CAChB;AACD;;;;;;;;AASA,IAAa,4BAAb,cAA+C,gBAAgB;;CAE9D;;CAEA;CAEA,YAAY,KAAa,QAAgB,YAA+B;EACvE,MAAM,KAAK,qDAAqD;EAChE,KAAK,SAAS;EACd,KAAK,aAAa;CACnB;AACD"}
@@ -0,0 +1,98 @@
1
+ Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
+ //#region src/events.ts
3
+ /** The event types a bucket's subscribers can name. */
4
+ const OBJECT_EVENT_TYPES = ["object.created", "object.deleted"];
5
+ /** A notification body that is not one the storage sends. */
6
+ var ObjectNotificationMalformed = class extends Error {
7
+ reason;
8
+ constructor(reason) {
9
+ super(`An object notification could not be read: ${reason}. A bucket's notifications are a JSON body with a 'Records' array, as S3 and MinIO send them — check what is publishing to this subscriber.`);
10
+ this.reason = reason;
11
+ this.name = "ObjectNotificationMalformed";
12
+ }
13
+ };
14
+ /**
15
+ * The object events in a notification body — S3's or MinIO's, as an object
16
+ * or as the JSON string SNS carries it in.
17
+ *
18
+ * A test event — S3 sends one when a notification is configured — is no
19
+ * event, so it reads as none. So does any record that is neither a write nor
20
+ * a delete: a restore, a replication, a lifecycle transition.
21
+ *
22
+ * @throws {ObjectNotificationMalformed} when the body is not a notification
23
+ */
24
+ function toObjectEvents(body) {
25
+ const notification = typeof body === "string" ? parse(body) : body;
26
+ if (!isRecord(notification)) throw new ObjectNotificationMalformed("it is not a JSON object");
27
+ if (isTestEvent(notification)) return [];
28
+ const { Records: records } = notification;
29
+ if (!Array.isArray(records)) throw new ObjectNotificationMalformed("it has no Records array");
30
+ const messages = [];
31
+ for (const record of records) {
32
+ if (!isRecord(record)) throw new ObjectNotificationMalformed("a record is not an object");
33
+ const type = eventType(record.eventName);
34
+ if (!type) continue;
35
+ const s3 = isRecord(record.s3) ? record.s3 : void 0;
36
+ const bucket = isRecord(s3?.bucket) ? s3.bucket.name : void 0;
37
+ const object = isRecord(s3?.object) ? s3.object : void 0;
38
+ if (typeof bucket !== "string" || typeof object?.key !== "string") throw new ObjectNotificationMalformed("a record names no bucket or no object key");
39
+ const payload = {
40
+ bucket,
41
+ key: decodeKey(object.key)
42
+ };
43
+ if (typeof object.size === "number") payload.size = object.size;
44
+ const etag = object.eTag ?? object.etag;
45
+ if (typeof etag === "string" && etag) payload.etag = etag.replace(/^"|"$/g, "");
46
+ if (typeof object.versionId === "string" && object.versionId) payload.versionId = object.versionId;
47
+ messages.push({
48
+ type,
49
+ payload
50
+ });
51
+ }
52
+ return messages;
53
+ }
54
+ /** Whether the event's key is under the filter's prefix and ends in its suffix. */
55
+ function matchesObjectFilter(event, filter = {}) {
56
+ if (filter.prefix && !event.key.startsWith(filter.prefix)) return false;
57
+ if (filter.suffix && !event.key.endsWith(filter.suffix)) return false;
58
+ return true;
59
+ }
60
+ /** `ObjectCreated:Put` or `s3:ObjectCreated:Put` → `object.created`. */
61
+ function eventType(name) {
62
+ if (typeof name !== "string") return void 0;
63
+ const bare = name.startsWith("s3:") ? name.slice(3) : name;
64
+ if (bare.startsWith("ObjectCreated:")) return "object.created";
65
+ if (bare.startsWith("ObjectRemoved:")) return "object.deleted";
66
+ }
67
+ /**
68
+ * A key as the storage encodes it in a notification: form-encoded, so a
69
+ * space is `+` and a literal `+` is `%2B`.
70
+ */
71
+ function decodeKey(key) {
72
+ const spaced = key.replace(/\+/g, " ");
73
+ try {
74
+ return decodeURIComponent(spaced);
75
+ } catch {
76
+ return spaced;
77
+ }
78
+ }
79
+ function isTestEvent(notification) {
80
+ return notification.Event === "s3:TestEvent" || notification.EventName === "s3:TestEvent";
81
+ }
82
+ function parse(body) {
83
+ try {
84
+ return JSON.parse(body);
85
+ } catch {
86
+ throw new ObjectNotificationMalformed("it is not JSON");
87
+ }
88
+ }
89
+ function isRecord(value) {
90
+ return typeof value === "object" && value !== null && !Array.isArray(value);
91
+ }
92
+ //#endregion
93
+ exports.OBJECT_EVENT_TYPES = OBJECT_EVENT_TYPES;
94
+ exports.ObjectNotificationMalformed = ObjectNotificationMalformed;
95
+ exports.matchesObjectFilter = matchesObjectFilter;
96
+ exports.toObjectEvents = toObjectEvents;
97
+
98
+ //# sourceMappingURL=events.cjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"events.cjs","names":[],"sources":["../src/events.ts"],"sourcesContent":["/**\n * Object events — what a bucket says happened to its objects, in words that\n * name no cloud.\n *\n * S3 and MinIO notify in the same shape: a body with `Records`, each naming\n * the event (`ObjectCreated:Put`, or `s3:ObjectCreated:Put` on MinIO) and the\n * object, its key URL-encoded the way a form is (`a+b.png` for `a b.png`).\n * This reads either into `{ type: 'object.created', payload }`, the message\n * shape every subscriber already handles.\n */\n\n/** What happened to an object. */\nexport type ObjectEventType = 'object.created' | 'object.deleted';\n\n/** The event types a bucket's subscribers can name. */\nexport const OBJECT_EVENT_TYPES: readonly ObjectEventType[] = [\n\t'object.created',\n\t'object.deleted',\n];\n\n/** One object, as an event names it. */\nexport interface ObjectEvent {\n\t/** The bucket's name, as the storage knows it. */\n\tbucket: string;\n\t/** The object's key, decoded. */\n\tkey: string;\n\t/** Its size in bytes. Absent on a delete. */\n\tsize?: number;\n\t/** Its entity tag, quotes removed. Absent on a delete. */\n\tetag?: string;\n\t/** The version written or removed, on a versioned bucket. */\n\tversionId?: string;\n}\n\n/** An object event as a message: what a subscriber is handed. */\nexport interface ObjectMessage<\n\tTType extends ObjectEventType = ObjectEventType,\n> {\n\ttype: TType;\n\tpayload: ObjectEvent;\n}\n\n/** Which keys a subscriber wants: those under `prefix` and ending in `suffix`. */\nexport interface ObjectFilter {\n\tprefix?: string;\n\tsuffix?: string;\n}\n\n/** A notification body that is not one the storage sends. */\nexport class ObjectNotificationMalformed extends Error {\n\tconstructor(readonly reason: string) {\n\t\tsuper(\n\t\t\t`An object notification could not be read: ${reason}. A bucket's ` +\n\t\t\t\t`notifications are a JSON body with a 'Records' array, as S3 and ` +\n\t\t\t\t`MinIO send them — check what is publishing to this subscriber.`,\n\t\t);\n\t\tthis.name = 'ObjectNotificationMalformed';\n\t}\n}\n\n/**\n * The object events in a notification body — S3's or MinIO's, as an object\n * or as the JSON string SNS carries it in.\n *\n * A test event — S3 sends one when a notification is configured — is no\n * event, so it reads as none. So does any record that is neither a write nor\n * a delete: a restore, a replication, a lifecycle transition.\n *\n * @throws {ObjectNotificationMalformed} when the body is not a notification\n */\nexport function toObjectEvents(body: unknown): ObjectMessage[] {\n\tconst notification = typeof body === 'string' ? parse(body) : body;\n\tif (!isRecord(notification)) {\n\t\tthrow new ObjectNotificationMalformed('it is not a JSON object');\n\t}\n\tif (isTestEvent(notification)) return [];\n\n\tconst { Records: records } = notification;\n\tif (!Array.isArray(records)) {\n\t\tthrow new ObjectNotificationMalformed('it has no Records array');\n\t}\n\n\tconst messages: ObjectMessage[] = [];\n\tfor (const record of records) {\n\t\tif (!isRecord(record)) {\n\t\t\tthrow new ObjectNotificationMalformed('a record is not an object');\n\t\t}\n\t\tconst type = eventType(record.eventName);\n\t\tif (!type) continue;\n\n\t\tconst s3 = isRecord(record.s3) ? record.s3 : undefined;\n\t\tconst bucket = isRecord(s3?.bucket) ? s3.bucket.name : undefined;\n\t\tconst object = isRecord(s3?.object) ? s3.object : undefined;\n\t\tif (typeof bucket !== 'string' || typeof object?.key !== 'string') {\n\t\t\tthrow new ObjectNotificationMalformed(\n\t\t\t\t'a record names no bucket or no object key',\n\t\t\t);\n\t\t}\n\n\t\tconst payload: ObjectEvent = { bucket, key: decodeKey(object.key) };\n\t\tif (typeof object.size === 'number') payload.size = object.size;\n\t\tconst etag = object.eTag ?? object.etag;\n\t\tif (typeof etag === 'string' && etag) {\n\t\t\tpayload.etag = etag.replace(/^\"|\"$/g, '');\n\t\t}\n\t\tif (typeof object.versionId === 'string' && object.versionId) {\n\t\t\tpayload.versionId = object.versionId;\n\t\t}\n\t\tmessages.push({ type, payload });\n\t}\n\treturn messages;\n}\n\n/** Whether the event's key is under the filter's prefix and ends in its suffix. */\nexport function matchesObjectFilter(\n\tevent: Pick<ObjectEvent, 'key'>,\n\tfilter: ObjectFilter = {},\n): boolean {\n\tif (filter.prefix && !event.key.startsWith(filter.prefix)) return false;\n\tif (filter.suffix && !event.key.endsWith(filter.suffix)) return false;\n\treturn true;\n}\n\n/** `ObjectCreated:Put` or `s3:ObjectCreated:Put` → `object.created`. */\nfunction eventType(name: unknown): ObjectEventType | undefined {\n\tif (typeof name !== 'string') return undefined;\n\tconst bare = name.startsWith('s3:') ? name.slice(3) : name;\n\tif (bare.startsWith('ObjectCreated:')) return 'object.created';\n\tif (bare.startsWith('ObjectRemoved:')) return 'object.deleted';\n\treturn undefined;\n}\n\n/**\n * A key as the storage encodes it in a notification: form-encoded, so a\n * space is `+` and a literal `+` is `%2B`.\n */\nfunction decodeKey(key: string): string {\n\tconst spaced = key.replace(/\\+/g, ' ');\n\ttry {\n\t\treturn decodeURIComponent(spaced);\n\t} catch {\n\t\t// A lone `%` the storage did not encode: the key as written.\n\t\treturn spaced;\n\t}\n}\n\nfunction isTestEvent(notification: Record<string, unknown>): boolean {\n\treturn (\n\t\tnotification.Event === 's3:TestEvent' ||\n\t\tnotification.EventName === 's3:TestEvent'\n\t);\n}\n\nfunction parse(body: string): unknown {\n\ttry {\n\t\treturn JSON.parse(body);\n\t} catch {\n\t\tthrow new ObjectNotificationMalformed('it is not JSON');\n\t}\n}\n\nfunction isRecord(value: unknown): value is Record<string, any> {\n\treturn typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n"],"mappings":";;;AAeA,MAAa,qBAAiD,CAC7D,kBACA,gBACD;;AA+BA,IAAa,8BAAb,cAAiD,MAAM;CACjC;CAArB,YAAY,QAAyB;EACpC,MACC,6CAA6C,OAAO,4IAGrD;EALoB,KAAA,SAAA;EAMpB,KAAK,OAAO;CACb;AACD;;;;;;;;;;;AAYA,SAAgB,eAAe,MAAgC;CAC9D,MAAM,eAAe,OAAO,SAAS,WAAW,MAAM,IAAI,IAAI;CAC9D,IAAI,CAAC,SAAS,YAAY,GACzB,MAAM,IAAI,4BAA4B,yBAAyB;CAEhE,IAAI,YAAY,YAAY,GAAG,OAAO,CAAC;CAEvC,MAAM,EAAE,SAAS,YAAY;CAC7B,IAAI,CAAC,MAAM,QAAQ,OAAO,GACzB,MAAM,IAAI,4BAA4B,yBAAyB;CAGhE,MAAM,WAA4B,CAAC;CACnC,KAAK,MAAM,UAAU,SAAS;EAC7B,IAAI,CAAC,SAAS,MAAM,GACnB,MAAM,IAAI,4BAA4B,2BAA2B;EAElE,MAAM,OAAO,UAAU,OAAO,SAAS;EACvC,IAAI,CAAC,MAAM;EAEX,MAAM,KAAK,SAAS,OAAO,EAAE,IAAI,OAAO,KAAK,KAAA;EAC7C,MAAM,SAAS,SAAS,IAAI,MAAM,IAAI,GAAG,OAAO,OAAO,KAAA;EACvD,MAAM,SAAS,SAAS,IAAI,MAAM,IAAI,GAAG,SAAS,KAAA;EAClD,IAAI,OAAO,WAAW,YAAY,OAAO,QAAQ,QAAQ,UACxD,MAAM,IAAI,4BACT,2CACD;EAGD,MAAM,UAAuB;GAAE;GAAQ,KAAK,UAAU,OAAO,GAAG;EAAE;EAClE,IAAI,OAAO,OAAO,SAAS,UAAU,QAAQ,OAAO,OAAO;EAC3D,MAAM,OAAO,OAAO,QAAQ,OAAO;EACnC,IAAI,OAAO,SAAS,YAAY,MAC/B,QAAQ,OAAO,KAAK,QAAQ,UAAU,EAAE;EAEzC,IAAI,OAAO,OAAO,cAAc,YAAY,OAAO,WAClD,QAAQ,YAAY,OAAO;EAE5B,SAAS,KAAK;GAAE;GAAM;EAAQ,CAAC;CAChC;CACA,OAAO;AACR;;AAGA,SAAgB,oBACf,OACA,SAAuB,CAAC,GACd;CACV,IAAI,OAAO,UAAU,CAAC,MAAM,IAAI,WAAW,OAAO,MAAM,GAAG,OAAO;CAClE,IAAI,OAAO,UAAU,CAAC,MAAM,IAAI,SAAS,OAAO,MAAM,GAAG,OAAO;CAChE,OAAO;AACR;;AAGA,SAAS,UAAU,MAA4C;CAC9D,IAAI,OAAO,SAAS,UAAU,OAAO,KAAA;CACrC,MAAM,OAAO,KAAK,WAAW,KAAK,IAAI,KAAK,MAAM,CAAC,IAAI;CACtD,IAAI,KAAK,WAAW,gBAAgB,GAAG,OAAO;CAC9C,IAAI,KAAK,WAAW,gBAAgB,GAAG,OAAO;AAE/C;;;;;AAMA,SAAS,UAAU,KAAqB;CACvC,MAAM,SAAS,IAAI,QAAQ,OAAO,GAAG;CACrC,IAAI;EACH,OAAO,mBAAmB,MAAM;CACjC,QAAQ;EAEP,OAAO;CACR;AACD;AAEA,SAAS,YAAY,cAAgD;CACpE,OACC,aAAa,UAAU,kBACvB,aAAa,cAAc;AAE7B;AAEA,SAAS,MAAM,MAAuB;CACrC,IAAI;EACH,OAAO,KAAK,MAAM,IAAI;CACvB,QAAQ;EACP,MAAM,IAAI,4BAA4B,gBAAgB;CACvD;AACD;AAEA,SAAS,SAAS,OAA8C;CAC/D,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC3E"}
@@ -0,0 +1,58 @@
1
+ //#region src/events.d.ts
2
+ /**
3
+ * Object events — what a bucket says happened to its objects, in words that
4
+ * name no cloud.
5
+ *
6
+ * S3 and MinIO notify in the same shape: a body with `Records`, each naming
7
+ * the event (`ObjectCreated:Put`, or `s3:ObjectCreated:Put` on MinIO) and the
8
+ * object, its key URL-encoded the way a form is (`a+b.png` for `a b.png`).
9
+ * This reads either into `{ type: 'object.created', payload }`, the message
10
+ * shape every subscriber already handles.
11
+ */
12
+ /** What happened to an object. */
13
+ export type ObjectEventType = 'object.created' | 'object.deleted';
14
+ /** The event types a bucket's subscribers can name. */
15
+ export declare const OBJECT_EVENT_TYPES: readonly ObjectEventType[];
16
+ /** One object, as an event names it. */
17
+ export interface ObjectEvent {
18
+ /** The bucket's name, as the storage knows it. */
19
+ bucket: string;
20
+ /** The object's key, decoded. */
21
+ key: string;
22
+ /** Its size in bytes. Absent on a delete. */
23
+ size?: number;
24
+ /** Its entity tag, quotes removed. Absent on a delete. */
25
+ etag?: string;
26
+ /** The version written or removed, on a versioned bucket. */
27
+ versionId?: string;
28
+ }
29
+ /** An object event as a message: what a subscriber is handed. */
30
+ export interface ObjectMessage<TType extends ObjectEventType = ObjectEventType> {
31
+ type: TType;
32
+ payload: ObjectEvent;
33
+ }
34
+ /** Which keys a subscriber wants: those under `prefix` and ending in `suffix`. */
35
+ export interface ObjectFilter {
36
+ prefix?: string;
37
+ suffix?: string;
38
+ }
39
+ /** A notification body that is not one the storage sends. */
40
+ export declare class ObjectNotificationMalformed extends Error {
41
+ readonly reason: string;
42
+ constructor(reason: string);
43
+ }
44
+ /**
45
+ * The object events in a notification body — S3's or MinIO's, as an object
46
+ * or as the JSON string SNS carries it in.
47
+ *
48
+ * A test event — S3 sends one when a notification is configured — is no
49
+ * event, so it reads as none. So does any record that is neither a write nor
50
+ * a delete: a restore, a replication, a lifecycle transition.
51
+ *
52
+ * @throws {ObjectNotificationMalformed} when the body is not a notification
53
+ */
54
+ export declare function toObjectEvents(body: unknown): ObjectMessage[];
55
+ /** Whether the event's key is under the filter's prefix and ends in its suffix. */
56
+ export declare function matchesObjectFilter(event: Pick<ObjectEvent, 'key'>, filter?: ObjectFilter): boolean;
57
+ //#endregion
58
+ //# sourceMappingURL=events.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"events.d.cts","names":[],"sources":["../src/events.ts"],"mappings":";;;;;;;;;;;;YAYY;;qBAGC,6BAA6B;;iBAMzB;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;;iBAIgB,cAChB,cAAc,kBAAkB;EAEhC,MAAM;EACN,SAAS;;;iBAIO;EAChB;EACA;;;qBAIY,oCAAoC;WAC3B;EAArB,YAAqB;;;;;;;;;;;;wBAoBN,eAAe,gBAAgB;;wBA4C/B,oBACf,OAAO,KAAK,qBACZ,SAAQ"}
@@ -0,0 +1,58 @@
1
+ //#region src/events.d.ts
2
+ /**
3
+ * Object events — what a bucket says happened to its objects, in words that
4
+ * name no cloud.
5
+ *
6
+ * S3 and MinIO notify in the same shape: a body with `Records`, each naming
7
+ * the event (`ObjectCreated:Put`, or `s3:ObjectCreated:Put` on MinIO) and the
8
+ * object, its key URL-encoded the way a form is (`a+b.png` for `a b.png`).
9
+ * This reads either into `{ type: 'object.created', payload }`, the message
10
+ * shape every subscriber already handles.
11
+ */
12
+ /** What happened to an object. */
13
+ export type ObjectEventType = 'object.created' | 'object.deleted';
14
+ /** The event types a bucket's subscribers can name. */
15
+ export declare const OBJECT_EVENT_TYPES: readonly ObjectEventType[];
16
+ /** One object, as an event names it. */
17
+ export interface ObjectEvent {
18
+ /** The bucket's name, as the storage knows it. */
19
+ bucket: string;
20
+ /** The object's key, decoded. */
21
+ key: string;
22
+ /** Its size in bytes. Absent on a delete. */
23
+ size?: number;
24
+ /** Its entity tag, quotes removed. Absent on a delete. */
25
+ etag?: string;
26
+ /** The version written or removed, on a versioned bucket. */
27
+ versionId?: string;
28
+ }
29
+ /** An object event as a message: what a subscriber is handed. */
30
+ export interface ObjectMessage<TType extends ObjectEventType = ObjectEventType> {
31
+ type: TType;
32
+ payload: ObjectEvent;
33
+ }
34
+ /** Which keys a subscriber wants: those under `prefix` and ending in `suffix`. */
35
+ export interface ObjectFilter {
36
+ prefix?: string;
37
+ suffix?: string;
38
+ }
39
+ /** A notification body that is not one the storage sends. */
40
+ export declare class ObjectNotificationMalformed extends Error {
41
+ readonly reason: string;
42
+ constructor(reason: string);
43
+ }
44
+ /**
45
+ * The object events in a notification body — S3's or MinIO's, as an object
46
+ * or as the JSON string SNS carries it in.
47
+ *
48
+ * A test event — S3 sends one when a notification is configured — is no
49
+ * event, so it reads as none. So does any record that is neither a write nor
50
+ * a delete: a restore, a replication, a lifecycle transition.
51
+ *
52
+ * @throws {ObjectNotificationMalformed} when the body is not a notification
53
+ */
54
+ export declare function toObjectEvents(body: unknown): ObjectMessage[];
55
+ /** Whether the event's key is under the filter's prefix and ends in its suffix. */
56
+ export declare function matchesObjectFilter(event: Pick<ObjectEvent, 'key'>, filter?: ObjectFilter): boolean;
57
+ //#endregion
58
+ //# sourceMappingURL=events.d.mts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"events.d.mts","names":[],"sources":["../src/events.ts"],"mappings":";;;;;;;;;;;;YAYY;;qBAGC,6BAA6B;;iBAMzB;;EAEhB;;EAEA;;EAEA;;EAEA;;EAEA;;;iBAIgB,cAChB,cAAc,kBAAkB;EAEhC,MAAM;EACN,SAAS;;;iBAIO;EAChB;EACA;;;qBAIY,oCAAoC;WAC3B;EAArB,YAAqB;;;;;;;;;;;;wBAoBN,eAAe,gBAAgB;;wBA4C/B,oBACf,OAAO,KAAK,qBACZ,SAAQ"}
@@ -0,0 +1,94 @@
1
+ //#region src/events.ts
2
+ /** The event types a bucket's subscribers can name. */
3
+ const OBJECT_EVENT_TYPES = ["object.created", "object.deleted"];
4
+ /** A notification body that is not one the storage sends. */
5
+ var ObjectNotificationMalformed = class extends Error {
6
+ reason;
7
+ constructor(reason) {
8
+ super(`An object notification could not be read: ${reason}. A bucket's notifications are a JSON body with a 'Records' array, as S3 and MinIO send them — check what is publishing to this subscriber.`);
9
+ this.reason = reason;
10
+ this.name = "ObjectNotificationMalformed";
11
+ }
12
+ };
13
+ /**
14
+ * The object events in a notification body — S3's or MinIO's, as an object
15
+ * or as the JSON string SNS carries it in.
16
+ *
17
+ * A test event — S3 sends one when a notification is configured — is no
18
+ * event, so it reads as none. So does any record that is neither a write nor
19
+ * a delete: a restore, a replication, a lifecycle transition.
20
+ *
21
+ * @throws {ObjectNotificationMalformed} when the body is not a notification
22
+ */
23
+ function toObjectEvents(body) {
24
+ const notification = typeof body === "string" ? parse(body) : body;
25
+ if (!isRecord(notification)) throw new ObjectNotificationMalformed("it is not a JSON object");
26
+ if (isTestEvent(notification)) return [];
27
+ const { Records: records } = notification;
28
+ if (!Array.isArray(records)) throw new ObjectNotificationMalformed("it has no Records array");
29
+ const messages = [];
30
+ for (const record of records) {
31
+ if (!isRecord(record)) throw new ObjectNotificationMalformed("a record is not an object");
32
+ const type = eventType(record.eventName);
33
+ if (!type) continue;
34
+ const s3 = isRecord(record.s3) ? record.s3 : void 0;
35
+ const bucket = isRecord(s3?.bucket) ? s3.bucket.name : void 0;
36
+ const object = isRecord(s3?.object) ? s3.object : void 0;
37
+ if (typeof bucket !== "string" || typeof object?.key !== "string") throw new ObjectNotificationMalformed("a record names no bucket or no object key");
38
+ const payload = {
39
+ bucket,
40
+ key: decodeKey(object.key)
41
+ };
42
+ if (typeof object.size === "number") payload.size = object.size;
43
+ const etag = object.eTag ?? object.etag;
44
+ if (typeof etag === "string" && etag) payload.etag = etag.replace(/^"|"$/g, "");
45
+ if (typeof object.versionId === "string" && object.versionId) payload.versionId = object.versionId;
46
+ messages.push({
47
+ type,
48
+ payload
49
+ });
50
+ }
51
+ return messages;
52
+ }
53
+ /** Whether the event's key is under the filter's prefix and ends in its suffix. */
54
+ function matchesObjectFilter(event, filter = {}) {
55
+ if (filter.prefix && !event.key.startsWith(filter.prefix)) return false;
56
+ if (filter.suffix && !event.key.endsWith(filter.suffix)) return false;
57
+ return true;
58
+ }
59
+ /** `ObjectCreated:Put` or `s3:ObjectCreated:Put` → `object.created`. */
60
+ function eventType(name) {
61
+ if (typeof name !== "string") return void 0;
62
+ const bare = name.startsWith("s3:") ? name.slice(3) : name;
63
+ if (bare.startsWith("ObjectCreated:")) return "object.created";
64
+ if (bare.startsWith("ObjectRemoved:")) return "object.deleted";
65
+ }
66
+ /**
67
+ * A key as the storage encodes it in a notification: form-encoded, so a
68
+ * space is `+` and a literal `+` is `%2B`.
69
+ */
70
+ function decodeKey(key) {
71
+ const spaced = key.replace(/\+/g, " ");
72
+ try {
73
+ return decodeURIComponent(spaced);
74
+ } catch {
75
+ return spaced;
76
+ }
77
+ }
78
+ function isTestEvent(notification) {
79
+ return notification.Event === "s3:TestEvent" || notification.EventName === "s3:TestEvent";
80
+ }
81
+ function parse(body) {
82
+ try {
83
+ return JSON.parse(body);
84
+ } catch {
85
+ throw new ObjectNotificationMalformed("it is not JSON");
86
+ }
87
+ }
88
+ function isRecord(value) {
89
+ return typeof value === "object" && value !== null && !Array.isArray(value);
90
+ }
91
+ //#endregion
92
+ export { OBJECT_EVENT_TYPES, ObjectNotificationMalformed, matchesObjectFilter, toObjectEvents };
93
+
94
+ //# sourceMappingURL=events.mjs.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"events.mjs","names":[],"sources":["../src/events.ts"],"sourcesContent":["/**\n * Object events — what a bucket says happened to its objects, in words that\n * name no cloud.\n *\n * S3 and MinIO notify in the same shape: a body with `Records`, each naming\n * the event (`ObjectCreated:Put`, or `s3:ObjectCreated:Put` on MinIO) and the\n * object, its key URL-encoded the way a form is (`a+b.png` for `a b.png`).\n * This reads either into `{ type: 'object.created', payload }`, the message\n * shape every subscriber already handles.\n */\n\n/** What happened to an object. */\nexport type ObjectEventType = 'object.created' | 'object.deleted';\n\n/** The event types a bucket's subscribers can name. */\nexport const OBJECT_EVENT_TYPES: readonly ObjectEventType[] = [\n\t'object.created',\n\t'object.deleted',\n];\n\n/** One object, as an event names it. */\nexport interface ObjectEvent {\n\t/** The bucket's name, as the storage knows it. */\n\tbucket: string;\n\t/** The object's key, decoded. */\n\tkey: string;\n\t/** Its size in bytes. Absent on a delete. */\n\tsize?: number;\n\t/** Its entity tag, quotes removed. Absent on a delete. */\n\tetag?: string;\n\t/** The version written or removed, on a versioned bucket. */\n\tversionId?: string;\n}\n\n/** An object event as a message: what a subscriber is handed. */\nexport interface ObjectMessage<\n\tTType extends ObjectEventType = ObjectEventType,\n> {\n\ttype: TType;\n\tpayload: ObjectEvent;\n}\n\n/** Which keys a subscriber wants: those under `prefix` and ending in `suffix`. */\nexport interface ObjectFilter {\n\tprefix?: string;\n\tsuffix?: string;\n}\n\n/** A notification body that is not one the storage sends. */\nexport class ObjectNotificationMalformed extends Error {\n\tconstructor(readonly reason: string) {\n\t\tsuper(\n\t\t\t`An object notification could not be read: ${reason}. A bucket's ` +\n\t\t\t\t`notifications are a JSON body with a 'Records' array, as S3 and ` +\n\t\t\t\t`MinIO send them — check what is publishing to this subscriber.`,\n\t\t);\n\t\tthis.name = 'ObjectNotificationMalformed';\n\t}\n}\n\n/**\n * The object events in a notification body — S3's or MinIO's, as an object\n * or as the JSON string SNS carries it in.\n *\n * A test event — S3 sends one when a notification is configured — is no\n * event, so it reads as none. So does any record that is neither a write nor\n * a delete: a restore, a replication, a lifecycle transition.\n *\n * @throws {ObjectNotificationMalformed} when the body is not a notification\n */\nexport function toObjectEvents(body: unknown): ObjectMessage[] {\n\tconst notification = typeof body === 'string' ? parse(body) : body;\n\tif (!isRecord(notification)) {\n\t\tthrow new ObjectNotificationMalformed('it is not a JSON object');\n\t}\n\tif (isTestEvent(notification)) return [];\n\n\tconst { Records: records } = notification;\n\tif (!Array.isArray(records)) {\n\t\tthrow new ObjectNotificationMalformed('it has no Records array');\n\t}\n\n\tconst messages: ObjectMessage[] = [];\n\tfor (const record of records) {\n\t\tif (!isRecord(record)) {\n\t\t\tthrow new ObjectNotificationMalformed('a record is not an object');\n\t\t}\n\t\tconst type = eventType(record.eventName);\n\t\tif (!type) continue;\n\n\t\tconst s3 = isRecord(record.s3) ? record.s3 : undefined;\n\t\tconst bucket = isRecord(s3?.bucket) ? s3.bucket.name : undefined;\n\t\tconst object = isRecord(s3?.object) ? s3.object : undefined;\n\t\tif (typeof bucket !== 'string' || typeof object?.key !== 'string') {\n\t\t\tthrow new ObjectNotificationMalformed(\n\t\t\t\t'a record names no bucket or no object key',\n\t\t\t);\n\t\t}\n\n\t\tconst payload: ObjectEvent = { bucket, key: decodeKey(object.key) };\n\t\tif (typeof object.size === 'number') payload.size = object.size;\n\t\tconst etag = object.eTag ?? object.etag;\n\t\tif (typeof etag === 'string' && etag) {\n\t\t\tpayload.etag = etag.replace(/^\"|\"$/g, '');\n\t\t}\n\t\tif (typeof object.versionId === 'string' && object.versionId) {\n\t\t\tpayload.versionId = object.versionId;\n\t\t}\n\t\tmessages.push({ type, payload });\n\t}\n\treturn messages;\n}\n\n/** Whether the event's key is under the filter's prefix and ends in its suffix. */\nexport function matchesObjectFilter(\n\tevent: Pick<ObjectEvent, 'key'>,\n\tfilter: ObjectFilter = {},\n): boolean {\n\tif (filter.prefix && !event.key.startsWith(filter.prefix)) return false;\n\tif (filter.suffix && !event.key.endsWith(filter.suffix)) return false;\n\treturn true;\n}\n\n/** `ObjectCreated:Put` or `s3:ObjectCreated:Put` → `object.created`. */\nfunction eventType(name: unknown): ObjectEventType | undefined {\n\tif (typeof name !== 'string') return undefined;\n\tconst bare = name.startsWith('s3:') ? name.slice(3) : name;\n\tif (bare.startsWith('ObjectCreated:')) return 'object.created';\n\tif (bare.startsWith('ObjectRemoved:')) return 'object.deleted';\n\treturn undefined;\n}\n\n/**\n * A key as the storage encodes it in a notification: form-encoded, so a\n * space is `+` and a literal `+` is `%2B`.\n */\nfunction decodeKey(key: string): string {\n\tconst spaced = key.replace(/\\+/g, ' ');\n\ttry {\n\t\treturn decodeURIComponent(spaced);\n\t} catch {\n\t\t// A lone `%` the storage did not encode: the key as written.\n\t\treturn spaced;\n\t}\n}\n\nfunction isTestEvent(notification: Record<string, unknown>): boolean {\n\treturn (\n\t\tnotification.Event === 's3:TestEvent' ||\n\t\tnotification.EventName === 's3:TestEvent'\n\t);\n}\n\nfunction parse(body: string): unknown {\n\ttry {\n\t\treturn JSON.parse(body);\n\t} catch {\n\t\tthrow new ObjectNotificationMalformed('it is not JSON');\n\t}\n}\n\nfunction isRecord(value: unknown): value is Record<string, any> {\n\treturn typeof value === 'object' && value !== null && !Array.isArray(value);\n}\n"],"mappings":";;AAeA,MAAa,qBAAiD,CAC7D,kBACA,gBACD;;AA+BA,IAAa,8BAAb,cAAiD,MAAM;CACjC;CAArB,YAAY,QAAyB;EACpC,MACC,6CAA6C,OAAO,4IAGrD;EALoB,KAAA,SAAA;EAMpB,KAAK,OAAO;CACb;AACD;;;;;;;;;;;AAYA,SAAgB,eAAe,MAAgC;CAC9D,MAAM,eAAe,OAAO,SAAS,WAAW,MAAM,IAAI,IAAI;CAC9D,IAAI,CAAC,SAAS,YAAY,GACzB,MAAM,IAAI,4BAA4B,yBAAyB;CAEhE,IAAI,YAAY,YAAY,GAAG,OAAO,CAAC;CAEvC,MAAM,EAAE,SAAS,YAAY;CAC7B,IAAI,CAAC,MAAM,QAAQ,OAAO,GACzB,MAAM,IAAI,4BAA4B,yBAAyB;CAGhE,MAAM,WAA4B,CAAC;CACnC,KAAK,MAAM,UAAU,SAAS;EAC7B,IAAI,CAAC,SAAS,MAAM,GACnB,MAAM,IAAI,4BAA4B,2BAA2B;EAElE,MAAM,OAAO,UAAU,OAAO,SAAS;EACvC,IAAI,CAAC,MAAM;EAEX,MAAM,KAAK,SAAS,OAAO,EAAE,IAAI,OAAO,KAAK,KAAA;EAC7C,MAAM,SAAS,SAAS,IAAI,MAAM,IAAI,GAAG,OAAO,OAAO,KAAA;EACvD,MAAM,SAAS,SAAS,IAAI,MAAM,IAAI,GAAG,SAAS,KAAA;EAClD,IAAI,OAAO,WAAW,YAAY,OAAO,QAAQ,QAAQ,UACxD,MAAM,IAAI,4BACT,2CACD;EAGD,MAAM,UAAuB;GAAE;GAAQ,KAAK,UAAU,OAAO,GAAG;EAAE;EAClE,IAAI,OAAO,OAAO,SAAS,UAAU,QAAQ,OAAO,OAAO;EAC3D,MAAM,OAAO,OAAO,QAAQ,OAAO;EACnC,IAAI,OAAO,SAAS,YAAY,MAC/B,QAAQ,OAAO,KAAK,QAAQ,UAAU,EAAE;EAEzC,IAAI,OAAO,OAAO,cAAc,YAAY,OAAO,WAClD,QAAQ,YAAY,OAAO;EAE5B,SAAS,KAAK;GAAE;GAAM;EAAQ,CAAC;CAChC;CACA,OAAO;AACR;;AAGA,SAAgB,oBACf,OACA,SAAuB,CAAC,GACd;CACV,IAAI,OAAO,UAAU,CAAC,MAAM,IAAI,WAAW,OAAO,MAAM,GAAG,OAAO;CAClE,IAAI,OAAO,UAAU,CAAC,MAAM,IAAI,SAAS,OAAO,MAAM,GAAG,OAAO;CAChE,OAAO;AACR;;AAGA,SAAS,UAAU,MAA4C;CAC9D,IAAI,OAAO,SAAS,UAAU,OAAO,KAAA;CACrC,MAAM,OAAO,KAAK,WAAW,KAAK,IAAI,KAAK,MAAM,CAAC,IAAI;CACtD,IAAI,KAAK,WAAW,gBAAgB,GAAG,OAAO;CAC9C,IAAI,KAAK,WAAW,gBAAgB,GAAG,OAAO;AAE/C;;;;;AAMA,SAAS,UAAU,KAAqB;CACvC,MAAM,SAAS,IAAI,QAAQ,OAAO,GAAG;CACrC,IAAI;EACH,OAAO,mBAAmB,MAAM;CACjC,QAAQ;EAEP,OAAO;CACR;AACD;AAEA,SAAS,YAAY,cAAgD;CACpE,OACC,aAAa,UAAU,kBACvB,aAAa,cAAc;AAE7B;AAEA,SAAS,MAAM,MAAuB;CACrC,IAAI;EACH,OAAO,KAAK,MAAM,IAAI;CACvB,QAAQ;EACP,MAAM,IAAI,4BAA4B,gBAAgB;CACvD;AACD;AAEA,SAAS,SAAS,OAA8C;CAC/D,OAAO,OAAO,UAAU,YAAY,UAAU,QAAQ,CAAC,MAAM,QAAQ,KAAK;AAC3E"}
package/dist/index.cjs CHANGED
@@ -1,5 +1,5 @@
1
1
  Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
2
- const require_errors = require("./errors-Bexjg-j-.cjs");
2
+ const require_errors = require("./errors-BB8jdHif.cjs");
3
3
  //#region src/registry.ts
4
4
  /**
5
5
  * Driver registry — how a storage URL becomes a client without the caller
@@ -41,12 +41,14 @@ function schemeOf(url) {
41
41
  return separator === -1 ? "" : url.slice(0, separator + 1);
42
42
  }
43
43
  //#endregion
44
+ exports.IncompleteStorageCredentials = require_errors.IncompleteStorageCredentials;
44
45
  exports.MalformedStorageUrl = require_errors.MalformedStorageUrl;
45
46
  exports.MissingStorageBucket = require_errors.MissingStorageBucket;
46
47
  exports.StorageUrlError = require_errors.StorageUrlError;
47
48
  exports.UnexpectedStorageScheme = require_errors.UnexpectedStorageScheme;
48
49
  exports.UnregisteredStorageScheme = require_errors.UnregisteredStorageScheme;
49
50
  exports.createStorageClient = createStorageClient;
51
+ exports.redactStorageUrl = require_errors.redactStorageUrl;
50
52
  exports.registerStorageDriver = registerStorageDriver;
51
53
  exports.registeredStorageSchemes = registeredStorageSchemes;
52
54
 
package/dist/index.d.cts CHANGED
@@ -1,4 +1,4 @@
1
- import { i as registeredStorageSchemes, l as StorageClient, n as createStorageClient, r as registerStorageDriver, t as StorageDriver } from "./registry-ClEvHGpM.cjs";
1
+ import { d as UploadPost, f as UploadPostParams, i as registeredStorageSchemes, l as StorageClient, n as createStorageClient, r as registerStorageDriver, t as StorageDriver } from "./registry-DyBOtv6n.cjs";
2
2
  //#region src/errors.d.ts
3
3
  /**
4
4
  * Storage errors — shared by every implementation, not just S3.
@@ -14,10 +14,23 @@ import { i as registeredStorageSchemes, l as StorageClient, n as createStorageCl
14
14
  */
15
15
  /** Base for anything wrong with a storage URL, so callers may catch broadly. */
16
16
  export declare abstract class StorageUrlError extends Error {
17
- /** The URL that could not be used. */
17
+ /**
18
+ * The URL that could not be used, with any credentials it carried replaced
19
+ * by `REDACTED` — an error is logged, and a key in its userinfo would be
20
+ * logged with it.
21
+ */
18
22
  readonly url: string;
19
23
  constructor(url: string, message: string);
20
24
  }
25
+ /**
26
+ * Replace a URL's userinfo with `REDACTED`, so `s3://KEY:SECRET@uploads` can be
27
+ * logged as `s3://REDACTED@uploads`. A URL without userinfo comes back as is.
28
+ *
29
+ * A string the URL parser rejects is still redacted, up to its last `@`: an
30
+ * unencoded `/` in a secret is the commonest way to write a malformed one, and
31
+ * that string is exactly the one that ends up in an error.
32
+ */
33
+ export declare function redactStorageUrl(url: string): string;
21
34
  /** The string is not a URL at all. */
22
35
  export declare class MalformedStorageUrl extends StorageUrlError {
23
36
  constructor(url: string);
@@ -44,6 +57,17 @@ export declare class UnexpectedStorageScheme extends StorageUrlError {
44
57
  export declare class MissingStorageBucket extends StorageUrlError {
45
58
  constructor(url: string);
46
59
  }
60
+ /**
61
+ * The URL's userinfo carries one half of a key pair: an access key with no
62
+ * secret, or a secret with no access key. Either both are in the URL, or
63
+ * neither is and the provider's default credential chain applies — half a pair
64
+ * is never silently completed from the environment.
65
+ */
66
+ export declare class IncompleteStorageCredentials extends StorageUrlError {
67
+ /** Which half is missing: `'accessKeyId'` or `'secretAccessKey'`. */
68
+ readonly missing: 'accessKeyId' | 'secretAccessKey';
69
+ constructor(url: string, missing: 'accessKeyId' | 'secretAccessKey');
70
+ }
47
71
  /**
48
72
  * No driver is registered for the URL's scheme.
49
73
  *
@@ -59,5 +83,5 @@ export declare class UnregisteredStorageScheme extends StorageUrlError {
59
83
  constructor(url: string, scheme: string, registered: readonly string[]);
60
84
  }
61
85
  //#endregion
62
- export { type StorageClient, type StorageDriver, createStorageClient, registerStorageDriver, registeredStorageSchemes };
86
+ export { type StorageClient, type StorageDriver, type UploadPost, type UploadPostParams, createStorageClient, registerStorageDriver, registeredStorageSchemes };
63
87
  //# sourceMappingURL=index.d.cts.map
@@ -1 +1 @@
1
- {"version":3,"file":"index.d.cts","names":[],"sources":["../src/errors.ts"],"mappings":";;;;;;;;;;;;;;;8BAcsB,wBAAwB;;WAEpC;EAEG,YAAA,aAAa;;;qBAQb,4BAA4B;EAC5B,YAAA;;;;;;;qBAUA,gCAAgC;;WAEnC;;WAEA;EAEG,YAAA,aAAa,kBAAkB;;;;;;;;;qBAc/B,6BAA6B;EAC7B,YAAA;;;;;;;;;qBAYA,kCAAkC;;WAErC;;WAEA;EAEG,YAAA,aAAa,gBAAgB"}
1
+ {"version":3,"file":"index.d.cts","names":[],"sources":["../src/errors.ts"],"mappings":";;;;;;;;;;;;;;;8BAcsB,wBAAwB;;;;;;WAMpC;EAET,YAAY,aAAa;;;;;;;;;;wBAeV,iBAAiB;;qBAapB,4BAA4B;EACxC,YAAY;;;;;;;qBAUA,gCAAgC;;WAEnC;;WAEA;EAET,YAAY,aAAa,kBAAkB;;;;;;;;;qBAc/B,6BAA6B;EACzC,YAAY;;;;;;;;qBAWA,qCAAqC;;WAExC;EAET,YAAY,aAAa;;;;;;;;;qBAgBb,kCAAkC;;WAErC;;WAEA;EAET,YAAY,aAAa,gBAAgB"}