lemon-model 1.5.1 → 5.0.1

package/README.md

@@ -31,6 +31,7 @@ Frontend bundlers use the ESM build. Existing Node `require()` consumers use the
 | --- | --- | --- |
 | `types` | Shared request, identity, storage, and service shapes | Source types |
 | `cores` | Small shared transform helpers | Source tests |
+| `fields` | `@field()` annotations and `fieldsOf()` for model classes | `## Fields` below |
 | `socket` | Peer socket, network contract, WebSocket bridge, JSON chunk transport | `src/socket/README.md` |
 | `buffer` | Provider-neutral GenAI stream buffering and network adapters | `src/buffer/README.md` |
 | `genai` | Gemini-like `generateContent()` adapter over Lemon agents APIs | `src/genai/README.md` |
@@ -92,6 +93,28 @@ The network adapter can send `GenAIStreamEvent` over the shared socket/json-tran
 
 Provider probe tools are available under `tools/`, but provider SDKs are not part of the runtime package contract. Install the matching SDK in the workspace where you run a probe.
 
+## Fields
+
+`@field()` marks the stored fields of a model class; `fieldsOf()` lists them (since 5.0.0).
+
+```ts
+import { CoreModel, field, fieldsOf } from 'lemon-model';
+
+class PetModel extends CoreModel<'pet'> {
+    @field({ group: 'head' }) name?: string;
+    @field() age?: number;
+}
+fieldsOf(PetModel); // 16 CoreModel fields, then 'name', 'age'
+fieldsOf(PetModel, { group: 'head' }); // ['name']
+```
+
+- Order: declaration order, parent first. A redeclared field (`@field({ group: 'head' }) declare name?: string;`) keeps the parent position; options merge, child wins per key.
+- Options: `kind` (`data` default, `view`, `internal`), `group` (string or string[]). `specsOf(cls)` returns `{ name, kind, group, own }`.
+- `CORE_FIELDS` = `fieldsOf(CoreModel, { kinds: ['view', 'data'] })` (14). `fieldsOf(CoreModel)` adds `id`, `_id` (16).
+- Modes: legacy decorators (`experimentalDecorators: true`) and TS 5 standard decorators both work. The `fields` module sets `Symbol.metadata ??= Symbol.for('Symbol.metadata')` once for standard mode.
+- Storage: the list lives on the class under `Symbol.for('lemon-model:fields:v1')` (`FIELDS_KEY`), so the CJS and the ESM build read each other's lists. No `reflect-metadata`.
+- Compare field lists as sets in tests, not by order.
+
 ## Build Formats
 
 - CommonJS entry: `dist/index.js`

package/dist/esm/fields/index.js

@@ -0,0 +1,108 @@
+var _a;
+var _b;
+/**
+ * `fields/index.ts`
+ * - field annotations of a model class: `@field()`, `fieldsOf()`, `specsOf()`.
+ * - `field()` is dual-mode: legacy `(prototype, key)` (experimentalDecorators) and standard `(undefined, context)`.
+ * - the field list is attached to the class itself under a `Symbol.for` key (never a module-level map),
+ *   so the CJS and the ESM copy of this module read the same list.
+ *
+ * @author      Steve Jung <steve@lemoncloud.io>
+ * @date        2026-10-28 initial version (lemon-core v5 B4)
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+// polyfill: standard decorators need `Symbol.metadata` (missing on Node 24); `Symbol.for` keeps every copy on one symbol.
+(_a = (_b = Symbol).metadata) !== null && _a !== void 0 ? _a : (_b.metadata = Symbol.for('Symbol.metadata'));
+/** key of the own field list on a class (legacy) or on its metadata object (standard), shared by every module copy */
+export const FIELDS_KEY = Symbol.for('lemon-model:fields:v1');
+/** own (non-inherited) declaration list of a holder; created non-enumerable on first write */
+const ownDecls = (holder) => {
+    if (Object.prototype.hasOwnProperty.call(holder, FIELDS_KEY))
+        return holder[FIELDS_KEY];
+    const list = [];
+    Object.defineProperty(holder, FIELDS_KEY, { value: list, enumerable: false, configurable: true });
+    return list;
+};
+/**
+ * decorator factory of a model field (dual-mode).
+ * - legacy: `@field() name?: string;` with `experimentalDecorators: true`.
+ * - standard: same syntax with TS 5 standard decorators (needs `Symbol.metadata`, polyfilled above).
+ *
+ * @param opts  field options (`kind`, `group`)
+ */
+export const field = (opts = {}) => (target, context) => {
+    // standard call: (undefined, context) - store on the class metadata object
+    if (context && typeof context === 'object' && typeof context.kind === 'string') {
+        if (context.kind !== 'field')
+            throw new Error(`@field() supports class fields only (got ${context.kind})`);
+        if (context.static)
+            throw new Error(`@field() does not support static fields (${String(context.name)})`);
+        if (!context.metadata)
+            throw new Error(`@field() needs Symbol.metadata - ${String(context.name)}`);
+        ownDecls(context.metadata).push({ name: String(context.name), opts: Object.assign({}, opts) });
+        return undefined;
+    }
+    // legacy call: (prototype, key) - store on the class (constructor)
+    if (typeof target === 'function')
+        throw new Error(`@field() does not support static fields (${String(context)})`);
+    ownDecls(target.constructor).push({ name: String(context), opts: Object.assign({}, opts) });
+    return undefined;
+};
+/** constructor chain of `cls`, ordered root -> leaf */
+const chainOf = (cls) => {
+    const out = [];
+    for (let c = cls; c && c !== Function.prototype; c = Object.getPrototypeOf(c))
+        out.unshift(c);
+    return out;
+};
+/** own declarations of one constructor from both stores (legacy first, then standard metadata) */
+const declsOf = (ctor) => {
+    const res = [];
+    // legacy store: own property of the constructor
+    if (Object.prototype.hasOwnProperty.call(ctor, FIELDS_KEY))
+        res.push(...ctor[FIELDS_KEY]);
+    // standard store: own list in the constructor's own metadata object
+    const msym = Symbol.metadata;
+    const meta = msym && Object.prototype.hasOwnProperty.call(ctor, msym) ? ctor[msym] : undefined;
+    if (meta && Object.prototype.hasOwnProperty.call(meta, FIELDS_KEY))
+        res.push(...meta[FIELDS_KEY]);
+    return res;
+};
+/** normalize `group` option into a list */
+const asGroups = (group) => group === undefined ? [] : Array.isArray(group) ? [...group] : [group];
+/**
+ * merged field specs of a model class.
+ * - walks the chain root -> leaf; parent fields come first in declaration order.
+ * - a redeclared name keeps the parent position, options merge as `{ ...parent, ...child }`.
+ *
+ * @param cls   model class
+ */
+export const specsOf = (cls) => {
+    const merged = new Map();
+    // Map.set() on an existing key keeps its first (parent) position
+    chainOf(cls).forEach(ctor => declsOf(ctor).forEach(d => {
+        const prev = merged.get(d.name);
+        merged.set(d.name, { opts: Object.assign(Object.assign({}, (prev ? prev.opts : {})), d.opts), own: ctor === cls });
+    }));
+    return [...merged.entries()].map(([name, { opts, own }]) => {
+        var _a;
+        return ({
+            name,
+            kind: (_a = opts.kind) !== null && _a !== void 0 ? _a : 'data',
+            group: asGroups(opts.group),
+            own,
+        });
+    });
+};
+/**
+ * field names of a model class, filtered by query.
+ *
+ * @param cls   model class
+ * @param query optional `group` and `kinds` filter
+ */
+export const fieldsOf = (cls, query = {}) => specsOf(cls)
+    .filter(s => (query.group ? s.group.includes(query.group) : true))
+    .filter(s => (query.kinds ? query.kinds.includes(s.kind) : true))
+    .map(s => s.name);
+//# sourceMappingURL=index.js.map

package/dist/esm/fields/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/fields/index.ts"],"names":[],"mappings":"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"}

package/dist/esm/index.js

@@ -16,4 +16,6 @@ export * from './buffer/index.js';
 export * from './sync/index.js';
 export * from './progress/index.js';
 export * from './logtrace/index.js';
+// field annotations: `field`, `fieldsOf`, `specsOf`, `FIELDS_KEY` (lemon-core v5 B4)
+export * from './fields/index.js';
 //# sourceMappingURL=index.js.map

package/dist/esm/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AACH,cAAc,SAAS,CAAC;AACxB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,QAAQ,CAAC;AACvB,cAAc,YAAY,CAAC;AAC3B,cAAc,YAAY,CAAC;AAC3B,qFAAqF;AACrF,cAAc,UAAU,CAAC"}

package/dist/esm/types/core-storage.js

@@ -1,3 +1,12 @@
+var __decorate = (this && this.__decorate) || function (decorators, target, key, desc) {
+    var c = arguments.length, r = c < 3 ? target : desc === null ? desc = Object.getOwnPropertyDescriptor(target, key) : desc, d;
+    if (typeof Reflect === "object" && typeof Reflect.decorate === "function") r = Reflect.decorate(decorators, target, key, desc);
+    else for (var i = decorators.length - 1; i >= 0; i--) if (d = decorators[i]) r = (c < 3 ? d(r) : c > 3 ? d(target, key, r) : d(target, key)) || r;
+    return c > 3 && r && Object.defineProperty(target, key, r), r;
+};
+var __metadata = (this && this.__metadata) || function (k, v) {
+    if (typeof Reflect === "object" && typeof Reflect.metadata === "function") return Reflect.metadata(k, v);
+};
 /**
  * `core-storage.ts`
  * - common types for core storage
@@ -7,24 +16,85 @@
  * @date        2019-11-20 initial version
  * @date        2020-01-03 support cognito-identity
  * @date        2021-12-07 support SearchBody
+ * @date        2026-10-28 `CoreModel` as a class with `@field()` annotations (lemon-core v5 B4)
  *
  * @copyright   (C) lemoncloud.io 2019 - All Rights Reserved.
  */
-//NOTE! - BE WARE TO USE `ts-transformer-keys` DUE TO MISSING `ttypescript`
-export const CORE_FIELDS = [
-    '$',
-    'ns',
-    'type',
-    'stereo',
-    'sid',
-    'uid',
-    'gid',
-    'lock',
-    'next',
-    'meta',
-    'createdAt',
-    'updatedAt',
-    'deletedAt',
-    'error',
-];
+// field annotations for the `CoreModel` class
+import { field, fieldsOf } from '../fields/index.js';
+/**
+ * class: `CoreModel`
+ * - general model out of base Model to support the common usage
+ * - a class (not an interface) since 5.0.0: the fields carry `@field()` so `fieldsOf(CoreModel)` lists them.
+ * - keep public optional fields only (no methods, no private members): object literals and
+ *   `interface X extends CoreModel` must keep compiling.
+ */
+export class CoreModel {
+}
+__decorate([
+    field({ kind: 'view' }),
+    __metadata("design:type", Object)
+], CoreModel.prototype, "$", void 0);
+__decorate([
+    field(),
+    __metadata("design:type", String)
+], CoreModel.prototype, "ns", void 0);
+__decorate([
+    field(),
+    __metadata("design:type", String)
+], CoreModel.prototype, "type", void 0);
+__decorate([
+    field(),
+    __metadata("design:type", String)
+], CoreModel.prototype, "stereo", void 0);
+__decorate([
+    field(),
+    __metadata("design:type", String)
+], CoreModel.prototype, "sid", void 0);
+__decorate([
+    field(),
+    __metadata("design:type", String)
+], CoreModel.prototype, "uid", void 0);
+__decorate([
+    field(),
+    __metadata("design:type", String)
+], CoreModel.prototype, "gid", void 0);
+__decorate([
+    field(),
+    __metadata("design:type", Number)
+], CoreModel.prototype, "lock", void 0);
+__decorate([
+    field(),
+    __metadata("design:type", Number)
+], CoreModel.prototype, "next", void 0);
+__decorate([
+    field(),
+    __metadata("design:type", Object)
+], CoreModel.prototype, "meta", void 0);
+__decorate([
+    field(),
+    __metadata("design:type", Number)
+], CoreModel.prototype, "createdAt", void 0);
+__decorate([
+    field(),
+    __metadata("design:type", Number)
+], CoreModel.prototype, "updatedAt", void 0);
+__decorate([
+    field(),
+    __metadata("design:type", Number)
+], CoreModel.prototype, "deletedAt", void 0);
+__decorate([
+    field(),
+    __metadata("design:type", String)
+], CoreModel.prototype, "error", void 0);
+__decorate([
+    field({ kind: 'internal' }),
+    __metadata("design:type", String)
+], CoreModel.prototype, "id", void 0);
+__decorate([
+    field({ kind: 'internal' }),
+    __metadata("design:type", String)
+], CoreModel.prototype, "_id", void 0);
+// L1 core fields: view + data kinds of `CoreModel` (14, same order as the former literal list)
+export const CORE_FIELDS = fieldsOf(CoreModel, { kinds: ['view', 'data'] });
 //# sourceMappingURL=core-storage.js.map

package/dist/esm/types/core-storage.js.map

@@ -1 +1 @@
-{"version":3,"file":"core-storage.js","sourceRoot":"","sources":["../../../src/types/core-storage.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAwHH,2EAA2E;AAC3E,MAAM,CAAC,MAAM,WAAW,GAAa;IACjC,GAAG;IACH,IAAI;IACJ,MAAM;IACN,QAAQ;IACR,KAAK;IACL,KAAK;IACL,KAAK;IACL,MAAM;IACN,MAAM;IACN,MAAM;IACN,WAAW;IACX,WAAW;IACX,WAAW;IACX,OAAO;CACV,CAAC"}
+{"version":3,"file":"core-storage.js","sourceRoot":"","sources":["../../../src/types/core-storage.ts"],"names":[],"mappings":";;;;;;;;;AAAA;;;;;;;;;;;;GAYG;AACH,8CAA8C;AAC9C,OAAO,EAAE,KAAK,EAAE,QAAQ,EAAE,MAAM,WAAW,CAAC;AAwD5C;;;;;;GAMG;AACH,MAAM,OAAO,SAAS;CAuFrB;AAhFG;IADC,KAAK,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,CAAC;;oCACE;AAO1B;IADC,KAAK,EAAE;;qCACI;AAKZ;IADC,KAAK,EAAE;;uCACS;AAKjB;IADC,KAAK,EAAE;;yCACQ;AAKhB;IADC,KAAK,EAAE;;sCACK;AAKb;IADC,KAAK,EAAE;;sCACK;AAKb;IADC,KAAK,EAAE;;sCACK;AAKb;IADC,KAAK,EAAE;;uCACM;AAKd;IADC,KAAK,EAAE;;uCACM;AAKd;IADC,KAAK,EAAE;;uCACY;AAKpB;IADC,KAAK,EAAE;;4CACW;AAKnB;IADC,KAAK,EAAE;;4CACW;AAKnB;IADC,KAAK,EAAE;;4CACW;AAKnB;IADC,KAAK,EAAE;;wCACO;AAOf;IADC,KAAK,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;;qCAChB;AAKZ;IADC,KAAK,CAAC,EAAE,IAAI,EAAE,UAAU,EAAE,CAAC;;sCACf;AAGjB,+FAA+F;AAC/F,MAAM,CAAC,MAAM,WAAW,GAAa,QAAQ,CAAC,SAAS,EAAE,EAAE,KAAK,EAAE,CAAC,MAAM,EAAE,MAAM,CAAC,EAAE,CAAC,CAAC"}

package/dist/esm/types/core-types.js

@@ -10,6 +10,7 @@
  * @date        2024-12-20 optimized `NextIdentityCognito`
  * @date        2025-05-13 optimized `NextContext` with `Authorization` header
  * @date        2025-06-12 optimized `SearchBody` with `knn` support
+ * @date        2026-10-30 v5 B13: `NextContext.channel` and `NextContext.trace` (`NextTrace`).
  *
  * @copyright   (C) lemoncloud.io 2019 - All Rights Reserved.
  */

package/dist/esm/types/core-types.js.map

@@ -1 +1 @@
-{"version":3,"file":"core-types.js","sourceRoot":"","sources":["../../../src/types/core-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;GAcG"}
+{"version":3,"file":"core-types.js","sourceRoot":"","sources":["../../../src/types/core-types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/fields/index.d.ts

@@ -0,0 +1,55 @@
+/** key of the own field list on a class (legacy) or on its metadata object (standard), shared by every module copy */
+export declare const FIELDS_KEY: unique symbol;
+/** kind of a field: `data` (default, stored), `view` (read-only view like `$`), `internal` (keys like `id`, `_id`) */
+export declare type FieldKind = 'data' | 'view' | 'internal';
+/** options of `@field()` */
+export interface FieldOptions {
+    /** field kind (default `data`) */
+    kind?: FieldKind;
+    /** projection group(s) (ex: `head`) */
+    group?: string | string[];
+}
+/** one merged field spec (see `specsOf()`) */
+export interface FieldSpec {
+    /** field name */
+    name: string;
+    /** field kind after merge (default `data`) */
+    kind: FieldKind;
+    /** projection groups after merge */
+    group: string[];
+    /** true if the queried class itself declares this field */
+    own: boolean;
+}
+/** query of `fieldsOf()` */
+export interface FieldQuery {
+    /** only fields whose groups include this group */
+    group?: string;
+    /** only fields of these kinds */
+    kinds?: FieldKind[];
+}
+/** a class (abstract or not) that may carry field annotations */
+declare type FieldHost = abstract new (...args: any[]) => any;
+/**
+ * decorator factory of a model field (dual-mode).
+ * - legacy: `@field() name?: string;` with `experimentalDecorators: true`.
+ * - standard: same syntax with TS 5 standard decorators (needs `Symbol.metadata`, polyfilled above).
+ *
+ * @param opts  field options (`kind`, `group`)
+ */
+export declare const field: (opts?: FieldOptions) => (target: any, context: any) => any;
+/**
+ * merged field specs of a model class.
+ * - walks the chain root -> leaf; parent fields come first in declaration order.
+ * - a redeclared name keeps the parent position, options merge as `{ ...parent, ...child }`.
+ *
+ * @param cls   model class
+ */
+export declare const specsOf: (cls: FieldHost) => FieldSpec[];
+/**
+ * field names of a model class, filtered by query.
+ *
+ * @param cls   model class
+ * @param query optional `group` and `kinds` filter
+ */
+export declare const fieldsOf: (cls: FieldHost, query?: FieldQuery) => string[];
+export {};

package/dist/fields/index.js

@@ -0,0 +1,114 @@
+"use strict";
+var _a;
+var _b;
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.fieldsOf = exports.specsOf = exports.field = exports.FIELDS_KEY = void 0;
+/**
+ * `fields/index.ts`
+ * - field annotations of a model class: `@field()`, `fieldsOf()`, `specsOf()`.
+ * - `field()` is dual-mode: legacy `(prototype, key)` (experimentalDecorators) and standard `(undefined, context)`.
+ * - the field list is attached to the class itself under a `Symbol.for` key (never a module-level map),
+ *   so the CJS and the ESM copy of this module read the same list.
+ *
+ * @author      Steve Jung <steve@lemoncloud.io>
+ * @date        2026-10-28 initial version (lemon-core v5 B4)
+ *
+ * @copyright (C) 2026 LemonCloud Co Ltd. - All Rights Reserved.
+ */
+// polyfill: standard decorators need `Symbol.metadata` (missing on Node 24); `Symbol.for` keeps every copy on one symbol.
+(_a = (_b = Symbol).metadata) !== null && _a !== void 0 ? _a : (_b.metadata = Symbol.for('Symbol.metadata'));
+/** key of the own field list on a class (legacy) or on its metadata object (standard), shared by every module copy */
+exports.FIELDS_KEY = Symbol.for('lemon-model:fields:v1');
+/** own (non-inherited) declaration list of a holder; created non-enumerable on first write */
+const ownDecls = (holder) => {
+    if (Object.prototype.hasOwnProperty.call(holder, exports.FIELDS_KEY))
+        return holder[exports.FIELDS_KEY];
+    const list = [];
+    Object.defineProperty(holder, exports.FIELDS_KEY, { value: list, enumerable: false, configurable: true });
+    return list;
+};
+/**
+ * decorator factory of a model field (dual-mode).
+ * - legacy: `@field() name?: string;` with `experimentalDecorators: true`.
+ * - standard: same syntax with TS 5 standard decorators (needs `Symbol.metadata`, polyfilled above).
+ *
+ * @param opts  field options (`kind`, `group`)
+ */
+const field = (opts = {}) => (target, context) => {
+    // standard call: (undefined, context) - store on the class metadata object
+    if (context && typeof context === 'object' && typeof context.kind === 'string') {
+        if (context.kind !== 'field')
+            throw new Error(`@field() supports class fields only (got ${context.kind})`);
+        if (context.static)
+            throw new Error(`@field() does not support static fields (${String(context.name)})`);
+        if (!context.metadata)
+            throw new Error(`@field() needs Symbol.metadata - ${String(context.name)}`);
+        ownDecls(context.metadata).push({ name: String(context.name), opts: Object.assign({}, opts) });
+        return undefined;
+    }
+    // legacy call: (prototype, key) - store on the class (constructor)
+    if (typeof target === 'function')
+        throw new Error(`@field() does not support static fields (${String(context)})`);
+    ownDecls(target.constructor).push({ name: String(context), opts: Object.assign({}, opts) });
+    return undefined;
+};
+exports.field = field;
+/** constructor chain of `cls`, ordered root -> leaf */
+const chainOf = (cls) => {
+    const out = [];
+    for (let c = cls; c && c !== Function.prototype; c = Object.getPrototypeOf(c))
+        out.unshift(c);
+    return out;
+};
+/** own declarations of one constructor from both stores (legacy first, then standard metadata) */
+const declsOf = (ctor) => {
+    const res = [];
+    // legacy store: own property of the constructor
+    if (Object.prototype.hasOwnProperty.call(ctor, exports.FIELDS_KEY))
+        res.push(...ctor[exports.FIELDS_KEY]);
+    // standard store: own list in the constructor's own metadata object
+    const msym = Symbol.metadata;
+    const meta = msym && Object.prototype.hasOwnProperty.call(ctor, msym) ? ctor[msym] : undefined;
+    if (meta && Object.prototype.hasOwnProperty.call(meta, exports.FIELDS_KEY))
+        res.push(...meta[exports.FIELDS_KEY]);
+    return res;
+};
+/** normalize `group` option into a list */
+const asGroups = (group) => group === undefined ? [] : Array.isArray(group) ? [...group] : [group];
+/**
+ * merged field specs of a model class.
+ * - walks the chain root -> leaf; parent fields come first in declaration order.
+ * - a redeclared name keeps the parent position, options merge as `{ ...parent, ...child }`.
+ *
+ * @param cls   model class
+ */
+const specsOf = (cls) => {
+    const merged = new Map();
+    // Map.set() on an existing key keeps its first (parent) position
+    chainOf(cls).forEach(ctor => declsOf(ctor).forEach(d => {
+        const prev = merged.get(d.name);
+        merged.set(d.name, { opts: Object.assign(Object.assign({}, (prev ? prev.opts : {})), d.opts), own: ctor === cls });
+    }));
+    return [...merged.entries()].map(([name, { opts, own }]) => {
+        var _a;
+        return ({
+            name,
+            kind: (_a = opts.kind) !== null && _a !== void 0 ? _a : 'data',
+            group: asGroups(opts.group),
+            own,
+        });
+    });
+};
+exports.specsOf = specsOf;
+/**
+ * field names of a model class, filtered by query.
+ *
+ * @param cls   model class
+ * @param query optional `group` and `kinds` filter
+ */
+const fieldsOf = (cls, query = {}) => (0, exports.specsOf)(cls)
+    .filter(s => (query.group ? s.group.includes(query.group) : true))
+    .filter(s => (query.kinds ? query.kinds.includes(s.kind) : true))
+    .map(s => s.name);
+exports.fieldsOf = fieldsOf;
+//# sourceMappingURL=index.js.map

package/dist/fields/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/fields/index.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -16,3 +16,4 @@ export * from './buffer';
 export * from './sync';
 export * from './progress';
 export * from './logtrace';
+export * from './fields';

package/dist/index.js

@@ -32,4 +32,6 @@ __exportStar(require("./buffer"), exports);
 __exportStar(require("./sync"), exports);
 __exportStar(require("./progress"), exports);
 __exportStar(require("./logtrace"), exports);
+// field annotations: `field`, `fieldsOf`, `specsOf`, `FIELDS_KEY` (lemon-core v5 B4)
+__exportStar(require("./fields"), exports);
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;;GASG;AACH,0CAAwB;AACxB,0CAAwB;AACxB,2CAAyB;AACzB,0CAAwB;AACxB,2CAAyB;AACzB,yCAAuB;AACvB,6CAA2B;AAC3B,6CAA2B"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";;;;;;;;;;;;;;;;AAAA;;;;;;;;;GASG;AACH,0CAAwB;AACxB,0CAAwB;AACxB,2CAAyB;AACzB,0CAAwB;AACxB,2CAAyB;AACzB,yCAAuB;AACvB,6CAA2B;AAC3B,6CAA2B;AAC3B,qFAAqF;AACrF,2CAAyB"}

package/dist/types/core-storage.d.ts

@@ -1,15 +1,3 @@
-/**
- * `core-storage.ts`
- * - common types for core storage
- *
- *
- * @author      Steve Jung <steve@lemoncloud.io>
- * @date        2019-11-20 initial version
- * @date        2020-01-03 support cognito-identity
- * @date        2021-12-07 support SearchBody
- *
- * @copyright   (C) lemoncloud.io 2019 - All Rights Reserved.
- */
 /**
  * only for type information for internal partition-key.
  */
@@ -63,8 +51,11 @@ export interface InternalModel extends CoreModifier {
 /**
  * class: `CoreModel`
  * - general model out of base Model to support the common usage
+ * - a class (not an interface) since 5.0.0: the fields carry `@field()` so `fieldsOf(CoreModel)` lists them.
+ * - keep public optional fields only (no methods, no private members): object literals and
+ *   `interface X extends CoreModel` must keep compiling.
  */
-export interface CoreModel<ModelType extends string = string> extends StorageModel, InternalModel {
+export declare class CoreModel<ModelType extends string = string> implements StorageModel, InternalModel {
     /**
      * the last modifier info
      * - set automatically when model is created/updated/deleted.
@@ -122,5 +113,13 @@ export interface CoreModel<ModelType extends string = string> extends StorageMod
      * error message will be set if error occurred
      */
     error?: string;
+    /**
+     * unique id value. (from `StorageModel`)
+     */
+    id?: string;
+    /**
+     * internal partition-key (from `InternalKey`)
+     */
+    _id?: string;
 }
 export declare const CORE_FIELDS: string[];