nicot 1.4.0 → 1.4.1

package/README-CN.md

@@ -192,6 +192,7 @@ content: string;
 | QueryGreater/Less   | 数值比较              |
 | QueryIn / QueryNotIn| IN / NOT IN           |
 | QueryMatchBoolean   | 自动解析 true/false   |
+| QueryBase64Equal / QueryBase64NotEqual | base64 字符串解码为二进制后比较（配合 `@Base64BinaryColumn()`） |
 | QueryOperator       | 自定义操作符          |
 | QueryWrap           | 自定义表达式          |
 | QueryAnd / QueryOr  | 条件组合              |
@@ -199,6 +200,45 @@ content: string;
 
 ---
 
+## Base64 二进制列：`@Base64BinaryColumn()`
+
+`@Base64BinaryColumn()` 让你在**数据库里存原始二进制**，而在 实体 / DTO /
+OpenAPI 层面统统“伪装成”一个普通的 base64 `string` 字段：
+
+- 实体属性类型是 `string`（base64 字符串）。
+- OpenAPI 中以 `{ type: String, format: 'byte' }` 展示。
+- 通过 TypeORM `ValueTransformer`：写库时把 base64 字符串解码成 `Buffer`
+  （默认列类型 `bytea`），读取时再编码回 base64 字符串。
+
+```ts
+@Entity()
+export class Attachment extends IdBase() {
+  @Base64BinaryColumn({ required: true })
+  data: string; // 接口里是 base64，PostgreSQL 里是 bytea
+
+  // MySQL 可指定 blob 系列类型：
+  @Base64BinaryColumn({ columnType: 'longblob' })
+  thumbnail: string;
+}
+```
+
+**直接赋二进制也合法。** 虽然类型是 base64 `string`，但如果在你自己的代码里
+（例如 `repo.save`）直接赋了 `Buffer` / `Uint8Array` / `ArrayBuffer`，会被认为
+“这就是那段二进制”原样入库，校验同样通过；读出来时依然是 base64 字符串。
+
+**查询。** base64 二进制列本身就是可查询字段（不需要 `GetMutator`）。想在
+`findAll` 中按它过滤，给它挂上 `@QueryBase64Equal()`（或
+`@QueryBase64NotEqual()`）即可：传入的 base64 查询串会在绑定参数前被解码成
+`Buffer`，从而与列里存的二进制匹配。
+
+```ts
+@Base64BinaryColumn()
+@QueryBase64Equal()
+signature: string; // GET /attachment?signature=3q2+7w==
+```
+
+---
+
 ## GET Mutator（URL → 类型转换）
 
 URL 参数永远是 string。  

package/README.md

@@ -289,6 +289,7 @@ Common ones:
 | `@SimpleJsonColumn`  | `json`             | same as above               |
 | `@StringJsonColumn`  | `text` (stringified JSON) | same as above       |
 | `@EnumColumn(Enum)`  | enum or text       | enum validation             |
+| `@Base64BinaryColumn()` | `bytea` (binary)| base64 string / binary      |
 
 All of them accept an `options` parameter:
 
@@ -301,6 +302,46 @@ All of them accept an `options` parameter:
 displayName: string;
 ```
 
+### `@Base64BinaryColumn()` — base64 over the wire, binary in the database
+
+`@Base64BinaryColumn()` lets you store **raw binary** in the database while the
+entity / DTO / OpenAPI surface all behave like a plain **base64 `string`**:
+
+- The TS property type is `string` (a base64 string).
+- It is exposed to OpenAPI as `{ type: String, format: 'byte' }`.
+- A TypeORM `ValueTransformer` decodes the base64 string into a `Buffer` on the
+  way into the DB (`bytea` by default) and encodes it back to base64 on read.
+
+```ts
+@Entity()
+export class Attachment extends IdBase() {
+  @Base64BinaryColumn({ required: true })
+  data: string; // base64 in the API, bytea in PostgreSQL
+
+  // MySQL? pick a blob type:
+  @Base64BinaryColumn({ columnType: 'longblob' })
+  thumbnail: string;
+}
+```
+
+**Assigning raw binary directly.** Even though the type is a base64 `string`,
+if you assign a `Buffer` / `Uint8Array` / `ArrayBuffer` (e.g. from `repo.save`
+in your own code), it is treated as *the binary itself* and stored as-is —
+validation accepts it too. It still comes back out as a base64 string over the
+API.
+
+**Querying.** A base64 binary column is a normal queryable field (no
+`GetMutator` required). To filter on it in `findAll`, attach
+`@QueryBase64Equal()` (or `@QueryBase64NotEqual()`); the incoming base64 query
+string is decoded to a `Buffer` right before it is bound, so it matches the
+binary stored in the column:
+
+```ts
+@Base64BinaryColumn()
+@QueryBase64Equal()
+signature: string; // GET /attachment?signature=3q2+7w==
+```
+
 ---
 
 ## Access control decorators

package/dist/index.cjs

@@ -572,6 +572,8 @@ var require_typeorm = __commonJS({
 // index.ts
 var index_exports = {};
 __export(index_exports, {
+  Base64BinaryColumn: () => Base64BinaryColumn,
+  Base64BinaryTransformer: () => Base64BinaryTransformer,
   BindingColumn: () => BindingColumn,
   BindingValue: () => BindingValue,
   BlankCursorPaginationReturnMessageDto: () => BlankCursorPaginationReturnMessageDto,
@@ -604,6 +606,7 @@ __export(index_exports, {
   Inner: () => Inner,
   IntColumn: () => IntColumn,
   InternalColumn: () => InternalColumn,
+  IsBase64OrBinary: () => IsBase64OrBinary,
   JsonColumn: () => JsonColumn,
   NotChangeable: () => NotChangeable,
   NotColumn: () => NotColumn,
@@ -617,6 +620,8 @@ __export(index_exports, {
   PageSettingsDto: () => PageSettingsDto,
   PickPipe: () => PickPipe,
   QueryAnd: () => QueryAnd,
+  QueryBase64Equal: () => QueryBase64Equal,
+  QueryBase64NotEqual: () => QueryBase64NotEqual,
   QueryColumn: () => QueryColumn,
   QueryCondition: () => QueryCondition,
   QueryEqual: () => QueryEqual,
@@ -660,8 +665,10 @@ __export(index_exports, {
   applyQueryPropertyLike: () => applyQueryPropertyLike,
   applyQueryPropertySearch: () => applyQueryPropertySearch,
   applyQueryPropertyZeroNullable: () => applyQueryPropertyZeroNullable,
+  binaryToBuffer: () => binaryToBuffer,
   createGetMutator: () => createGetMutator,
   createQueryArrayify: () => createQueryArrayify,
+  createQueryBase64Operator: () => createQueryBase64Operator,
   createQueryCondition: () => createQueryCondition,
   createQueryOperator: () => createQueryOperator,
   createQueryOperatorArrayify: () => createQueryOperatorArrayify,
@@ -669,7 +676,8 @@ __export(index_exports, {
   getTransactionalEntityManagerProvider: () => getTransactionalEntityManagerProvider,
   getTransactionalEntityManagerToken: () => getTransactionalEntityManagerToken,
   getTransactionalRepositoryProvider: () => getTransactionalRepositoryProvider,
-  getTransactionalRepositoryToken: () => getTransactionalRepositoryToken
+  getTransactionalRepositoryToken: () => getTransactionalRepositoryToken,
+  isBinaryLike: () => isBinaryLike
 });
 module.exports = __toCommonJS(index_exports);
 var import_reflect_metadata = require("reflect-metadata");
@@ -914,6 +922,40 @@ var GetMutatorJson = createGetMutator((s) => JSON.parse(s), {
   example: `{"key1":"value1","key2":2,"key3":[1,2,3]}`
 });
 
+// src/utility/base64-binary.ts
+function isBinaryLike(value) {
+  return Buffer.isBuffer(value) || value instanceof Uint8Array || value instanceof ArrayBuffer;
+}
+function binaryToBuffer(value) {
+  if (Buffer.isBuffer(value)) {
+    return value;
+  }
+  if (value instanceof Uint8Array) {
+    return Buffer.from(value.buffer, value.byteOffset, value.byteLength);
+  }
+  return Buffer.from(new Uint8Array(value));
+}
+var Base64BinaryTransformer = class {
+  to(entValue) {
+    if (entValue == null) {
+      return entValue;
+    }
+    if (isBinaryLike(entValue)) {
+      return binaryToBuffer(entValue);
+    }
+    return Buffer.from(String(entValue), "base64");
+  }
+  from(dbValue) {
+    if (dbValue == null) {
+      return dbValue;
+    }
+    if (isBinaryLike(dbValue)) {
+      return binaryToBuffer(dbValue).toString("base64");
+    }
+    return Buffer.from(String(dbValue)).toString("base64");
+  }
+};
+
 // src/decorators/property.ts
 var NotRequiredButHasDefaultDec = () => Metadata.set(
   "notRequiredButHasDefault",
@@ -1136,6 +1178,29 @@ var StringJsonColumn = createJsonColumnDef(
   "text",
   TypeTransformerString
 );
+var IsBase64OrBinary = (validationOptions) => (0, import_class_validator3.ValidateBy)(
+  {
+    name: "isBase64OrBinary",
+    validator: {
+      validate: (value) => isBinaryLike(value) || typeof value === "string" && (0, import_class_validator3.isBase64)(value),
+      defaultMessage: (0, import_class_validator3.buildMessage)(
+        (eachPrefix) => `${eachPrefix}$property must be a base64 string or binary data (Buffer / Uint8Array / ArrayBuffer)`,
+        validationOptions
+      )
+    }
+  },
+  validationOptions
+);
+var Base64BinaryColumn = (options = {}) => (0, import_nesties4.MergePropertyDecorators)([
+  (0, import_typeorm.Column)(options.columnType || "bytea", {
+    ...columnDecoratorOptions(options),
+    default: void 0,
+    transformer: new Base64BinaryTransformer()
+  }),
+  IsBase64OrBinary(),
+  validatorDecorator(options),
+  swaggerDecorator(options, { type: String, format: "byte" })
+]);
 var NotColumn = (options = {}, specials = {}) => (0, import_nesties4.MergePropertyDecorators)([
   (0, import_class_transformer2.Exclude)(),
   swaggerDecorator({
@@ -1359,6 +1424,21 @@ var createQueryOperatorArrayify = (operator, singleFallback) => createQueryArray
 );
 var QueryIn = createQueryOperatorArrayify("IN", "=");
 var QueryNotIn = createQueryOperatorArrayify("NOT IN", "!=");
+var toBase64QueryBuffer = (value) => {
+  if (value == null) {
+    return value;
+  }
+  if (isBinaryLike(value)) {
+    return binaryToBuffer(value);
+  }
+  return Buffer.from(String(value), "base64");
+};
+var createQueryBase64Operator = (operator) => (field) => QueryWrap((entityExpr, varExpr, info) => {
+  info.mutateValue(toBase64QueryBuffer(info.value));
+  return `${entityExpr} ${operator} ${varExpr}`;
+}, field);
+var QueryBase64Equal = createQueryBase64Operator("=");
+var QueryBase64NotEqual = createQueryBase64Operator("!=");
 var QueryFullText = (options = {}) => {
   const configurationName = options.parser ? `nicot_parser_${options.parser}` : options.configuration || "english";
   const tsQueryFunction = options.tsQueryFunction || "websearch_to_tsquery";
@@ -4139,6 +4219,8 @@ TransactionalTypeOrmModule = __decorateClass([
 ], TransactionalTypeOrmModule);
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
+  Base64BinaryColumn,
+  Base64BinaryTransformer,
   BindingColumn,
   BindingValue,
   BlankCursorPaginationReturnMessageDto,
@@ -4171,6 +4253,7 @@ TransactionalTypeOrmModule = __decorateClass([
   Inner,
   IntColumn,
   InternalColumn,
+  IsBase64OrBinary,
   JsonColumn,
   NotChangeable,
   NotColumn,
@@ -4184,6 +4267,8 @@ TransactionalTypeOrmModule = __decorateClass([
   PageSettingsDto,
   PickPipe,
   QueryAnd,
+  QueryBase64Equal,
+  QueryBase64NotEqual,
   QueryColumn,
   QueryCondition,
   QueryEqual,
@@ -4227,8 +4312,10 @@ TransactionalTypeOrmModule = __decorateClass([
   applyQueryPropertyLike,
   applyQueryPropertySearch,
   applyQueryPropertyZeroNullable,
+  binaryToBuffer,
   createGetMutator,
   createQueryArrayify,
+  createQueryBase64Operator,
   createQueryCondition,
   createQueryOperator,
   createQueryOperatorArrayify,
@@ -4237,6 +4324,7 @@ TransactionalTypeOrmModule = __decorateClass([
   getTransactionalEntityManagerToken,
   getTransactionalRepositoryProvider,
   getTransactionalRepositoryToken,
+  isBinaryLike,
   ...require("nesties")
 });
 //# sourceMappingURL=index.cjs.map