@geekmidas/storage 10.0.0-alpha.123 → 10.0.0-alpha.124

package/dist/events.cjs

@@ -0,0 +1,98 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+//#region src/events.ts
+/** The event types a bucket's subscribers can name. */
+const OBJECT_EVENT_TYPES = ["object.created", "object.deleted"];
+/** A notification body that is not one the storage sends. */
+var ObjectNotificationMalformed = class extends Error {
+	reason;
+	constructor(reason) {
+		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.`);
+		this.reason = reason;
+		this.name = "ObjectNotificationMalformed";
+	}
+};
+/**
+* The object events in a notification body — S3's or MinIO's, as an object
+* or as the JSON string SNS carries it in.
+*
+* A test event — S3 sends one when a notification is configured — is no
+* event, so it reads as none. So does any record that is neither a write nor
+* a delete: a restore, a replication, a lifecycle transition.
+*
+* @throws {ObjectNotificationMalformed} when the body is not a notification
+*/
+function toObjectEvents(body) {
+	const notification = typeof body === "string" ? parse(body) : body;
+	if (!isRecord(notification)) throw new ObjectNotificationMalformed("it is not a JSON object");
+	if (isTestEvent(notification)) return [];
+	const { Records: records } = notification;
+	if (!Array.isArray(records)) throw new ObjectNotificationMalformed("it has no Records array");
+	const messages = [];
+	for (const record of records) {
+		if (!isRecord(record)) throw new ObjectNotificationMalformed("a record is not an object");
+		const type = eventType(record.eventName);
+		if (!type) continue;
+		const s3 = isRecord(record.s3) ? record.s3 : void 0;
+		const bucket = isRecord(s3?.bucket) ? s3.bucket.name : void 0;
+		const object = isRecord(s3?.object) ? s3.object : void 0;
+		if (typeof bucket !== "string" || typeof object?.key !== "string") throw new ObjectNotificationMalformed("a record names no bucket or no object key");
+		const payload = {
+			bucket,
+			key: decodeKey(object.key)
+		};
+		if (typeof object.size === "number") payload.size = object.size;
+		const etag = object.eTag ?? object.etag;
+		if (typeof etag === "string" && etag) payload.etag = etag.replace(/^"|"$/g, "");
+		if (typeof object.versionId === "string" && object.versionId) payload.versionId = object.versionId;
+		messages.push({
+			type,
+			payload
+		});
+	}
+	return messages;
+}
+/** Whether the event's key is under the filter's prefix and ends in its suffix. */
+function matchesObjectFilter(event, filter = {}) {
+	if (filter.prefix && !event.key.startsWith(filter.prefix)) return false;
+	if (filter.suffix && !event.key.endsWith(filter.suffix)) return false;
+	return true;
+}
+/** `ObjectCreated:Put` or `s3:ObjectCreated:Put` → `object.created`. */
+function eventType(name) {
+	if (typeof name !== "string") return void 0;
+	const bare = name.startsWith("s3:") ? name.slice(3) : name;
+	if (bare.startsWith("ObjectCreated:")) return "object.created";
+	if (bare.startsWith("ObjectRemoved:")) return "object.deleted";
+}
+/**
+* A key as the storage encodes it in a notification: form-encoded, so a
+* space is `+` and a literal `+` is `%2B`.
+*/
+function decodeKey(key) {
+	const spaced = key.replace(/\+/g, " ");
+	try {
+		return decodeURIComponent(spaced);
+	} catch {
+		return spaced;
+	}
+}
+function isTestEvent(notification) {
+	return notification.Event === "s3:TestEvent" || notification.EventName === "s3:TestEvent";
+}
+function parse(body) {
+	try {
+		return JSON.parse(body);
+	} catch {
+		throw new ObjectNotificationMalformed("it is not JSON");
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+exports.OBJECT_EVENT_TYPES = OBJECT_EVENT_TYPES;
+exports.ObjectNotificationMalformed = ObjectNotificationMalformed;
+exports.matchesObjectFilter = matchesObjectFilter;
+exports.toObjectEvents = toObjectEvents;
+
+//# sourceMappingURL=events.cjs.map

package/dist/events.cjs.map

@@ -0,0 +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"}

package/dist/events.d.cts

@@ -0,0 +1,58 @@
+//#region src/events.d.ts
+/**
+ * Object events — what a bucket says happened to its objects, in words that
+ * name no cloud.
+ *
+ * S3 and MinIO notify in the same shape: a body with `Records`, each naming
+ * the event (`ObjectCreated:Put`, or `s3:ObjectCreated:Put` on MinIO) and the
+ * object, its key URL-encoded the way a form is (`a+b.png` for `a b.png`).
+ * This reads either into `{ type: 'object.created', payload }`, the message
+ * shape every subscriber already handles.
+ */
+/** What happened to an object. */
+export type ObjectEventType = 'object.created' | 'object.deleted';
+/** The event types a bucket's subscribers can name. */
+export declare const OBJECT_EVENT_TYPES: readonly ObjectEventType[];
+/** One object, as an event names it. */
+export interface ObjectEvent {
+  /** The bucket's name, as the storage knows it. */
+  bucket: string;
+  /** The object's key, decoded. */
+  key: string;
+  /** Its size in bytes. Absent on a delete. */
+  size?: number;
+  /** Its entity tag, quotes removed. Absent on a delete. */
+  etag?: string;
+  /** The version written or removed, on a versioned bucket. */
+  versionId?: string;
+}
+/** An object event as a message: what a subscriber is handed. */
+export interface ObjectMessage<TType extends ObjectEventType = ObjectEventType> {
+  type: TType;
+  payload: ObjectEvent;
+}
+/** Which keys a subscriber wants: those under `prefix` and ending in `suffix`. */
+export interface ObjectFilter {
+  prefix?: string;
+  suffix?: string;
+}
+/** A notification body that is not one the storage sends. */
+export declare class ObjectNotificationMalformed extends Error {
+  readonly reason: string;
+  constructor(reason: string);
+}
+/**
+ * The object events in a notification body — S3's or MinIO's, as an object
+ * or as the JSON string SNS carries it in.
+ *
+ * A test event — S3 sends one when a notification is configured — is no
+ * event, so it reads as none. So does any record that is neither a write nor
+ * a delete: a restore, a replication, a lifecycle transition.
+ *
+ * @throws {ObjectNotificationMalformed} when the body is not a notification
+ */
+export declare function toObjectEvents(body: unknown): ObjectMessage[];
+/** Whether the event's key is under the filter's prefix and ends in its suffix. */
+export declare function matchesObjectFilter(event: Pick<ObjectEvent, 'key'>, filter?: ObjectFilter): boolean;
+//#endregion
+//# sourceMappingURL=events.d.cts.map

package/dist/events.d.cts.map

@@ -0,0 +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"}

package/dist/events.d.mts

@@ -0,0 +1,58 @@
+//#region src/events.d.ts
+/**
+ * Object events — what a bucket says happened to its objects, in words that
+ * name no cloud.
+ *
+ * S3 and MinIO notify in the same shape: a body with `Records`, each naming
+ * the event (`ObjectCreated:Put`, or `s3:ObjectCreated:Put` on MinIO) and the
+ * object, its key URL-encoded the way a form is (`a+b.png` for `a b.png`).
+ * This reads either into `{ type: 'object.created', payload }`, the message
+ * shape every subscriber already handles.
+ */
+/** What happened to an object. */
+export type ObjectEventType = 'object.created' | 'object.deleted';
+/** The event types a bucket's subscribers can name. */
+export declare const OBJECT_EVENT_TYPES: readonly ObjectEventType[];
+/** One object, as an event names it. */
+export interface ObjectEvent {
+  /** The bucket's name, as the storage knows it. */
+  bucket: string;
+  /** The object's key, decoded. */
+  key: string;
+  /** Its size in bytes. Absent on a delete. */
+  size?: number;
+  /** Its entity tag, quotes removed. Absent on a delete. */
+  etag?: string;
+  /** The version written or removed, on a versioned bucket. */
+  versionId?: string;
+}
+/** An object event as a message: what a subscriber is handed. */
+export interface ObjectMessage<TType extends ObjectEventType = ObjectEventType> {
+  type: TType;
+  payload: ObjectEvent;
+}
+/** Which keys a subscriber wants: those under `prefix` and ending in `suffix`. */
+export interface ObjectFilter {
+  prefix?: string;
+  suffix?: string;
+}
+/** A notification body that is not one the storage sends. */
+export declare class ObjectNotificationMalformed extends Error {
+  readonly reason: string;
+  constructor(reason: string);
+}
+/**
+ * The object events in a notification body — S3's or MinIO's, as an object
+ * or as the JSON string SNS carries it in.
+ *
+ * A test event — S3 sends one when a notification is configured — is no
+ * event, so it reads as none. So does any record that is neither a write nor
+ * a delete: a restore, a replication, a lifecycle transition.
+ *
+ * @throws {ObjectNotificationMalformed} when the body is not a notification
+ */
+export declare function toObjectEvents(body: unknown): ObjectMessage[];
+/** Whether the event's key is under the filter's prefix and ends in its suffix. */
+export declare function matchesObjectFilter(event: Pick<ObjectEvent, 'key'>, filter?: ObjectFilter): boolean;
+//#endregion
+//# sourceMappingURL=events.d.mts.map

package/dist/events.d.mts.map

@@ -0,0 +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"}

package/dist/events.mjs

@@ -0,0 +1,94 @@
+//#region src/events.ts
+/** The event types a bucket's subscribers can name. */
+const OBJECT_EVENT_TYPES = ["object.created", "object.deleted"];
+/** A notification body that is not one the storage sends. */
+var ObjectNotificationMalformed = class extends Error {
+	reason;
+	constructor(reason) {
+		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.`);
+		this.reason = reason;
+		this.name = "ObjectNotificationMalformed";
+	}
+};
+/**
+* The object events in a notification body — S3's or MinIO's, as an object
+* or as the JSON string SNS carries it in.
+*
+* A test event — S3 sends one when a notification is configured — is no
+* event, so it reads as none. So does any record that is neither a write nor
+* a delete: a restore, a replication, a lifecycle transition.
+*
+* @throws {ObjectNotificationMalformed} when the body is not a notification
+*/
+function toObjectEvents(body) {
+	const notification = typeof body === "string" ? parse(body) : body;
+	if (!isRecord(notification)) throw new ObjectNotificationMalformed("it is not a JSON object");
+	if (isTestEvent(notification)) return [];
+	const { Records: records } = notification;
+	if (!Array.isArray(records)) throw new ObjectNotificationMalformed("it has no Records array");
+	const messages = [];
+	for (const record of records) {
+		if (!isRecord(record)) throw new ObjectNotificationMalformed("a record is not an object");
+		const type = eventType(record.eventName);
+		if (!type) continue;
+		const s3 = isRecord(record.s3) ? record.s3 : void 0;
+		const bucket = isRecord(s3?.bucket) ? s3.bucket.name : void 0;
+		const object = isRecord(s3?.object) ? s3.object : void 0;
+		if (typeof bucket !== "string" || typeof object?.key !== "string") throw new ObjectNotificationMalformed("a record names no bucket or no object key");
+		const payload = {
+			bucket,
+			key: decodeKey(object.key)
+		};
+		if (typeof object.size === "number") payload.size = object.size;
+		const etag = object.eTag ?? object.etag;
+		if (typeof etag === "string" && etag) payload.etag = etag.replace(/^"|"$/g, "");
+		if (typeof object.versionId === "string" && object.versionId) payload.versionId = object.versionId;
+		messages.push({
+			type,
+			payload
+		});
+	}
+	return messages;
+}
+/** Whether the event's key is under the filter's prefix and ends in its suffix. */
+function matchesObjectFilter(event, filter = {}) {
+	if (filter.prefix && !event.key.startsWith(filter.prefix)) return false;
+	if (filter.suffix && !event.key.endsWith(filter.suffix)) return false;
+	return true;
+}
+/** `ObjectCreated:Put` or `s3:ObjectCreated:Put` → `object.created`. */
+function eventType(name) {
+	if (typeof name !== "string") return void 0;
+	const bare = name.startsWith("s3:") ? name.slice(3) : name;
+	if (bare.startsWith("ObjectCreated:")) return "object.created";
+	if (bare.startsWith("ObjectRemoved:")) return "object.deleted";
+}
+/**
+* A key as the storage encodes it in a notification: form-encoded, so a
+* space is `+` and a literal `+` is `%2B`.
+*/
+function decodeKey(key) {
+	const spaced = key.replace(/\+/g, " ");
+	try {
+		return decodeURIComponent(spaced);
+	} catch {
+		return spaced;
+	}
+}
+function isTestEvent(notification) {
+	return notification.Event === "s3:TestEvent" || notification.EventName === "s3:TestEvent";
+}
+function parse(body) {
+	try {
+		return JSON.parse(body);
+	} catch {
+		throw new ObjectNotificationMalformed("it is not JSON");
+	}
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+//#endregion
+export { OBJECT_EVENT_TYPES, ObjectNotificationMalformed, matchesObjectFilter, toObjectEvents };
+
+//# sourceMappingURL=events.mjs.map

package/dist/events.mjs.map

@@ -0,0 +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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@geekmidas/storage",
-  "version": "10.0.0-alpha.123",
+  "version": "10.0.0-alpha.124",
   "private": false,
   "repository": {
     "type": "git",
@@ -22,6 +22,16 @@
         "default": "./dist/aws.cjs"
       }
     },
+    "./events": {
+      "import": {
+        "types": "./dist/events.d.mts",
+        "default": "./dist/events.mjs"
+      },
+      "require": {
+        "types": "./dist/events.d.cts",
+        "default": "./dist/events.cjs"
+      }
+    },
     ".": {
       "import": {
         "types": "./dist/index.d.mts",
@@ -54,7 +64,7 @@
     "@aws-sdk/client-s3": ">=3.1136.0",
     "@aws-sdk/s3-presigned-post": ">=3.1136.0",
     "@aws-sdk/s3-request-presigner": ">=3.1136.0",
-    "@geekmidas/cache": "^10.0.0-alpha.123"
+    "@geekmidas/cache": "^10.0.0-alpha.124"
   },
   "peerDependenciesMeta": {
     "@geekmidas/cache": {
@@ -75,7 +85,7 @@
   },
   "devDependencies": {
     "@opentelemetry/sdk-trace-node": "~2.11.0",
-    "@geekmidas/cache": "^10.0.0-alpha.123"
+    "@geekmidas/cache": "^10.0.0-alpha.124"
   },
   "scripts": {
     "build": "tsdown --config ../../tsdown.config.ts --filter ."