@intlify/core-base 9.3.0-beta.26 → 9.3.0-beta.27

package/dist/core-base.cjs

@@ -1,5 +1,5 @@
 /*!
-  * core-base v9.3.0-beta.26
+  * core-base v9.3.0-beta.27
   * (c) 2023 kazuya kawaguchi
   * Released under the MIT License.
   */
@@ -398,7 +398,8 @@ function createMessageContext(options = {}) {
         ["message" /* HelperNameMap.MESSAGE */]: message,
         ["type" /* HelperNameMap.TYPE */]: type,
         ["interpolate" /* HelperNameMap.INTERPOLATE */]: interpolate,
-        ["normalize" /* HelperNameMap.NORMALIZE */]: normalize
+        ["normalize" /* HelperNameMap.NORMALIZE */]: normalize,
+        ["values" /* HelperNameMap.VALUES */]: shared.assign({}, _list, _named)
     };
     return ctx;
 }
@@ -432,7 +433,8 @@ const CoreWarnCodes = {
     FALLBACK_TO_NUMBER_FORMAT: 4,
     CANNOT_FORMAT_DATE: 5,
     FALLBACK_TO_DATE_FORMAT: 6,
-    __EXTEND_POINT__: 7
+    EXPERIMENTAL_CUSTOM_MESSAGE_COMPILER: 7,
+    __EXTEND_POINT__: 8
 };
 /** @internal */
 const warnMessages = {
@@ -441,7 +443,8 @@ const warnMessages = {
     [CoreWarnCodes.CANNOT_FORMAT_NUMBER]: `Cannot format a number value due to not supported Intl.NumberFormat.`,
     [CoreWarnCodes.FALLBACK_TO_NUMBER_FORMAT]: `Fall back to number format '{key}' key with '{target}' locale.`,
     [CoreWarnCodes.CANNOT_FORMAT_DATE]: `Cannot format a date value due to not supported Intl.DateTimeFormat.`,
-    [CoreWarnCodes.FALLBACK_TO_DATE_FORMAT]: `Fall back to datetime format '{key}' key with '{target}' locale.`
+    [CoreWarnCodes.FALLBACK_TO_DATE_FORMAT]: `Fall back to datetime format '{key}' key with '{target}' locale.`,
+    [CoreWarnCodes.EXPERIMENTAL_CUSTOM_MESSAGE_COMPILER]: `This project is using Custom Message Compiler, which is an experimental feature. It may receive breaking changes or be removed in the future.`
 };
 function getWarnMessage(code, ...args) {
     return shared.format(warnMessages[code], ...args);
@@ -568,7 +571,7 @@ function appendItemToChain(chain, target, blocks) {
  * Intlify core-base version
  * @internal
  */
-const VERSION = '9.3.0-beta.26';
+const VERSION = '9.3.0-beta.27';
 const NOT_REOSLVED = -1;
 const DEFAULT_LOCALE = 'en-US';
 const MISSING_RESOLVE_VALUE = '';
@@ -629,10 +632,10 @@ function registerLocaleFallbacker(fallbacker) {
 }
 // Additional Meta for Intlify DevTools
 let _additionalMeta =  null;
-const setAdditionalMeta =  (meta) => {
+const setAdditionalMeta = /* #__PURE__*/ (meta) => {
     _additionalMeta = meta;
 };
-const getAdditionalMeta =  () => _additionalMeta;
+const getAdditionalMeta = /* #__PURE__*/ () => _additionalMeta;
 let _fallbackContext = null;
 const setFallbackContext = (context) => {
     _fallbackContext = context;
@@ -642,6 +645,7 @@ const getFallbackContext = () => _fallbackContext;
 let _cid = 0;
 function createCoreContext(options = {}) {
     // setup options
+    const onWarn = shared.isFunction(options.onWarn) ? options.onWarn : shared.warn;
     const version = shared.isString(options.version) ? options.version : VERSION;
     const locale = shared.isString(options.locale) ? options.locale : DEFAULT_LOCALE;
     const fallbackLocale = shared.isArray(options.fallbackLocale) ||
@@ -683,6 +687,9 @@ function createCoreContext(options = {}) {
     const messageCompiler = shared.isFunction(options.messageCompiler)
         ? options.messageCompiler
         : _compiler;
+    if (shared.isFunction(options.messageCompiler)) {
+        shared.warnOnce(getWarnMessage(CoreWarnCodes.EXPERIMENTAL_CUSTOM_MESSAGE_COMPILER));
+    }
     const messageResolver = shared.isFunction(options.messageResolver)
         ? options.messageResolver
         : _resolver || resolveWithKeyValue;
@@ -692,7 +699,6 @@ function createCoreContext(options = {}) {
     const fallbackContext = shared.isObject(options.fallbackContext)
         ? options.fallbackContext
         : undefined;
-    const onWarn = shared.isFunction(options.onWarn) ? options.onWarn : shared.warn;
     // setup internal options
     const internalOptions = options;
     const __datetimeFormatters = shared.isObject(internalOptions.__datetimeFormatters)
@@ -850,14 +856,14 @@ function formatMessagePart(ctx, node) {
     }
 }
 
-let code = messageCompiler.CompileErrorCodes.__EXTEND_POINT__;
-const inc = () => ++code;
+const code = messageCompiler.CompileErrorCodes.__EXTEND_POINT__;
+const inc = shared.incrementer(code);
 const CoreErrorCodes = {
     INVALID_ARGUMENT: code,
     INVALID_DATE_ARGUMENT: inc(),
     INVALID_ISO_DATE_ARGUMENT: inc(),
-    NOT_SUPPORT_AST: inc(),
-    __EXTEND_POINT__: inc() // 19
+    NOT_SUPPORT_NON_STRING_MESSAGE: inc(),
+    __EXTEND_POINT__: inc() // 22
 };
 function createCoreError(code) {
     return messageCompiler.createCompileError(code, null, { messages: errorMessages } );
@@ -868,7 +874,7 @@ const errorMessages = {
     [CoreErrorCodes.INVALID_DATE_ARGUMENT]: 'The date provided is an invalid Date object.' +
         'Make sure your Date represents a valid date.',
     [CoreErrorCodes.INVALID_ISO_DATE_ARGUMENT]: 'The argument provided is not a valid ISO date string',
-    [CoreErrorCodes.NOT_SUPPORT_AST]: 'Not support AST'
+    [CoreErrorCodes.NOT_SUPPORT_NON_STRING_MESSAGE]: 'Not support non-string message'
 };
 
 const WARN_MESSAGE = `Detected HTML in '{source}' message. Recommend not using HTML messages to avoid XSS.`;
@@ -882,6 +888,9 @@ let compileCache = Object.create(null);
 function clearCompileCache() {
     compileCache = Object.create(null);
 }
+const isMessageAST = (val) => shared.isObject(val) &&
+    (val.t === 0 || val.type === 0) &&
+    ('b' in val || 'body' in val);
 function baseCompile(message, options = {}) {
     // error detecting on compile
     let detectError = false;
@@ -893,27 +902,25 @@ function baseCompile(message, options = {}) {
     // compile with mesasge-compiler
     return { ...messageCompiler.baseCompile(message, options), detectError };
 }
-function compileToFunction(message, options = {}) {
+function compileToFunction(message, context) {
     if (!shared.isString(message)) {
-        throw createCoreError(CoreErrorCodes.NOT_SUPPORT_AST);
+        throw createCoreError(CoreErrorCodes.NOT_SUPPORT_NON_STRING_MESSAGE);
     }
     {
         // check HTML message
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const warnHtmlMessage = shared.isBoolean(options.warnHtmlMessage)
-            ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                options.warnHtmlMessage
+        const warnHtmlMessage = shared.isBoolean(context.warnHtmlMessage)
+            ? context.warnHtmlMessage
             : true;
         checkHtmlMessage(message, warnHtmlMessage);
         // check caches
-        const onCacheKey = options.onCacheKey || defaultOnCacheKey;
+        const onCacheKey = context.onCacheKey || defaultOnCacheKey;
         const cacheKey = onCacheKey(message);
         const cached = compileCache[cacheKey];
         if (cached) {
             return cached;
         }
         // compile
-        const { code, detectError } = baseCompile(message, options);
+        const { code, detectError } = baseCompile(message, context);
         // evaluate function
         const msg = new Function(`return ${code}`)();
         // if occurred compile error, don't cache
@@ -922,36 +929,12 @@ function compileToFunction(message, options = {}) {
             : msg;
     }
 }
-function compile(message, options = {}) {
-    if (shared.isString(message)) {
-        // check HTML message
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        const warnHtmlMessage = shared.isBoolean(options.warnHtmlMessage)
-            ? // eslint-disable-next-line @typescript-eslint/no-explicit-any
-                options.warnHtmlMessage
-            : true;
-        checkHtmlMessage(message, warnHtmlMessage);
-        // check caches
-        const onCacheKey = options.onCacheKey || defaultOnCacheKey;
-        const cacheKey = onCacheKey(message);
-        const cached = compileCache[cacheKey];
-        if (cached) {
-            return cached;
+function compile(message, context) {
+    {
+        if (!isMessageAST(message)) {
+            shared.warn(`the message that is resolve with key '${context.key}') is not supported for jit compilation`);
+            return (() => message);
         }
-        // compile with JIT mode
-        const { ast, detectError } = baseCompile(message, {
-            ...options,
-            location: true,
-            jit: true
-        });
-        // compose message function from AST
-        const msg = format(ast);
-        // if occurred compile error, don't cache
-        return !detectError
-            ? (compileCache[cacheKey] = msg)
-            : msg;
-    }
-    else {
         // AST case (passed from bundler)
         const cacheKey = message.cacheKey;
         if (cacheKey) {
@@ -971,7 +954,6 @@ function compile(message, options = {}) {
 
 const NOOP_MESSAGE_FUNCTION = () => '';
 const isMessageFunction = (val) => shared.isFunction(val);
-const isMessageAST = (val) => shared.isObject(val) && val.type === 0 && 'body' in val;
 // implementation of `translate` function
 function translate(context, ...args) {
     const { fallbackFormat, postTranslation, unresolving, messageCompiler, fallbackLocale, messages } = context;
@@ -1042,12 +1024,12 @@ function translate(context, ...args) {
     }
     // setup compile error detecting
     let occurred = false;
-    const errorDetector = () => {
+    const onError = () => {
         occurred = true;
     };
     // compile message format
     const msg = !isMessageFunction(format)
-        ? compileMessageFormat(context, key, targetLocale, format, cacheBaseKey, errorDetector)
+        ? compileMessageFormat(context, key, targetLocale, format, cacheBaseKey, onError)
         : format;
     // if occurred compile error, return the message format
     if (occurred) {
@@ -1175,7 +1157,7 @@ function resolveMessageFormat(context, key, locale, fallbackLocale, fallbackWarn
     }
     return [format, targetLocale, message];
 }
-function compileMessageFormat(context, key, targetLocale, format, cacheBaseKey, errorDetector) {
+function compileMessageFormat(context, key, targetLocale, format, cacheBaseKey, onError) {
     const { messageCompiler, warnHtmlMessage } = context;
     if (isMessageFunction(format)) {
         const msg = format;
@@ -1199,7 +1181,7 @@ function compileMessageFormat(context, key, targetLocale, format, cacheBaseKey,
         endTag = 'intlify-message-compilation-end';
         shared.mark && shared.mark(startTag);
     }
-    const msg = messageCompiler(format, getCompileOptions(context, targetLocale, cacheBaseKey, format, warnHtmlMessage, errorDetector));
+    const msg = messageCompiler(format, getCompileContext(context, targetLocale, cacheBaseKey, format, warnHtmlMessage, onError));
     // for vue-devtools timeline event
     if (shared.inBrowser) {
         const end = window.performance.now();
@@ -1292,11 +1274,13 @@ function parseTranslateArgs(...args) {
     }
     return [key, options];
 }
-function getCompileOptions(context, locale, key, source, warnHtmlMessage, errorDetector) {
+function getCompileContext(context, locale, key, source, warnHtmlMessage, onError) {
     return {
+        locale,
+        key,
         warnHtmlMessage,
         onError: (err) => {
-            errorDetector && errorDetector(err);
+            onError && onError(err);
             {
                 const _source = getSourceForCodeFrame(source);
                 const message = `Message compilation error: ${err.message}`;
@@ -1338,10 +1322,10 @@ function getMessageContextOptions(context, locale, message, options) {
         }
         if (shared.isString(val) || isMessageAST(val)) {
             let occurred = false;
-            const errorDetector = () => {
+            const onError = () => {
                 occurred = true;
             };
-            const msg = compileMessageFormat(context, key, locale, val, key, errorDetector);
+            const msg = compileMessageFormat(context, key, locale, val, key, onError);
             return !occurred
                 ? msg
                 : NOOP_MESSAGE_FUNCTION;

package/dist/core-base.d.ts

@@ -1,3 +1,4 @@
+import type { BaseError } from '@intlify/shared';
 import { CompileError } from '@intlify/message-compiler';
 import { CompileErrorCodes } from '@intlify/message-compiler';
 import type { CompileOptions } from '@intlify/message-compiler';
@@ -18,15 +19,11 @@ export declare function clearCompileCache(): void;
 
 /* Excluded from this release type: clearNumberFormat */
 
-export declare function compile<Message = string, MessageSource extends string | ResourceNode = string>(message: MessageSource, options?: CoreBaseCompileOptions): MessageFunction<Message>;
+export declare function compile<Message = string, MessageSource = string | ResourceNode>(message: MessageSource, context: MessageCompilerContext): MessageFunction<Message>;
 export { CompileError }
 export { CompileErrorCodes }
 
-export declare function compileToFunction<Message = string, MessageSource extends string | ResourceNode = string>(message: MessageSource, options?: CoreBaseCompileOptions): MessageFunction<Message>;
-
-declare type CoreBaseCompileOptions = CompileOptions & {
-    warnHtmlMessage?: boolean;
-};
+export declare function compileToFunction<Message = string, MessageSource = string | ResourceNode>(message: MessageSource, context: MessageCompilerContext): MessageFunction<Message>;
 
 export declare interface CoreCommonContext<Message = string, Locales = 'en-US'> {
     cid: number;
@@ -52,15 +49,14 @@ export declare interface CoreDateTimeContext<DateTimeFormats = {}> {
     };
 }
 
-export declare interface CoreError extends CompileError {
-    code: CoreErrorCodes;
+export declare interface CoreError extends BaseError {
 }
 
 export declare const CoreErrorCodes: {
-    readonly INVALID_ARGUMENT: 15;
+    readonly INVALID_ARGUMENT: 17;
     readonly INVALID_DATE_ARGUMENT: number;
     readonly INVALID_ISO_DATE_ARGUMENT: number;
-    readonly NOT_SUPPORT_AST: number;
+    readonly NOT_SUPPORT_NON_STRING_MESSAGE: number;
     readonly __EXTEND_POINT__: number;
 };
 
@@ -167,7 +163,8 @@ export declare const CoreWarnCodes: {
     readonly FALLBACK_TO_NUMBER_FORMAT: 4;
     readonly CANNOT_FORMAT_DATE: 5;
     readonly FALLBACK_TO_DATE_FORMAT: 6;
-    readonly __EXTEND_POINT__: 7;
+    readonly EXPERIMENTAL_CUSTOM_MESSAGE_COMPILER: 7;
+    readonly __EXTEND_POINT__: 8;
 };
 
 export declare type CoreWarnCodes = (typeof CoreWarnCodes)[keyof typeof CoreWarnCodes];
@@ -399,7 +396,13 @@ export declare type LinkedModifiers<T = string> = {
 export declare type LinkedModify<T = string> = (value: T, type: string) => MessageType<T>;
 
 export declare interface LinkedOptions {
+    /**
+     * The message type of linked message
+     */
     type?: string;
+    /**
+     * The modifier of linked message
+     */
     modifier?: string;
 }
 
@@ -462,19 +465,160 @@ export declare type LocaleRecord<T extends any[], R> = {
     [K in T[number]]: R;
 };
 
-export declare type MessageCompiler<Message = string, MessageSource extends string | ResourceNode = string> = (message: MessageSource, options?: CompileOptions) => MessageFunction<Message>;
+/**
+ * The message compiler
+ *
+ * @param message - A resolved message that ususally will be passed the string. if you can transform to it with bundler, will be passed the AST.
+ * @param context - A message context {@link MessageCompilerContext}
+ *
+ * @returns A {@link MessageFunction}
+ *
+ * @VueI18nGeneral
+ */
+export declare type MessageCompiler<Message = string, MessageSource = string | ResourceNode> = (message: MessageSource, context: MessageCompilerContext) => MessageFunction<Message>;
 
+/**
+ * The context that will pass the message compiler.
+ *
+ * @VueI18nGeneral
+ */
+export declare type MessageCompilerContext = Pick<CompileOptions, 'onError' | 'onCacheKey'> & {
+    /**
+     * Whether to allow the use locale messages of HTML formatting.
+     */
+    warnHtmlMessage?: boolean;
+    /**
+     * The resolved locale message key
+     */
+    key: string;
+    /**
+     * The locale
+     */
+    locale: Locale;
+};
+
+/**
+ * The message context.
+ *
+ * @VueI18nGeneral
+ */
 export declare interface MessageContext<T = string> {
+    /**
+     * Resolve message value from list.
+     *
+     * @param index - An index of message values.
+     *
+     * @returns A resolved message value.
+     *
+     * @example
+     * ```js
+     * const messages = {
+     *   en: {
+     *     greeting: ({ list }) => `hello, ${list(0)}!`
+     *   }
+     * }
+     * ```
+     */
     list(index: number): unknown;
+    /**
+     * Resolve message value from named.
+     *
+     * @param key - A key of message value.
+     *
+     * @returns A resolved message value.
+     *
+     * @example
+     * ```js
+     * const messages = {
+     *   en: {
+     *     greeting: ({ named }) => `hello, ${named('name')}!`
+     *   }
+     * }
+     * ```
+     */
     named(key: string): unknown;
+    /**
+     * Resolve message with plural index.
+     *
+     * @remarks
+     * That's resolved with plural index with translation function.
+     *
+     * @param messages - the messages, that is resolved with plural index with translation function.
+     *
+     * @returns A resolved message.
+     *
+     * @example
+     * ```js
+     * const messages = {
+     *   en: {
+     *     car: ({ plural }) => plural(['car', 'cars']),
+     *     apple: ({ plural, named }) =>
+     *       plural([
+     *         'no apples',
+     *         'one apple',
+     *         `${named('count')} apples`
+     *       ])
+     *   }
+     * }
+     * ```
+     */
     plural(messages: T[]): T;
+    /**
+     * Resolve linked message.
+     *
+     * @param key - A message key
+     * @param modifier - A modifier
+     *
+     * @returns A resolve message.
+     */
     linked(key: Path, modifier?: string): MessageType<T>;
+    /**
+     * Overloaded `linked`
+     *
+     * @param key - A message key
+     * @param modifier - A modifier
+     * @param type - A message type
+     *
+     * @returns A resolve message.
+     */
     linked(key: Path, modifier?: string, type?: string): MessageType<T>;
+    /**
+     * Overloaded `linked`
+     *
+     * @param key - A message key
+     * @param optoins - An {@link LinkedOptions | linked options}
+     *
+     * @returns A resolve message.
+     */
     linked(key: Path, optoins?: LinkedOptions): MessageType<T>;
-    message(key: Path): MessageFunction<T>;
+    /* Excluded from this release type: message */
+    /**
+     * The message type to be handled by the message function.
+     *
+     * @remarks
+     * Usually `text`, you need to return **string** in message function.
+     */
     type: string;
-    interpolate: MessageInterpolate<T>;
-    normalize: MessageNormalize<T>;
+    /* Excluded from this release type: interpolate */
+    /* Excluded from this release type: normalize */
+    /**
+     * The message values.
+     *
+     * @remarks
+     * The message values are the argument values passed from translation fucntion, such as `$t`, `t`, or `translate`.
+     *
+     * @example
+     * vue-i18n `$t` (or `t`) case:
+     * ```html
+     * <p>{{ $t('greeting', { name: 'DIO' }) }}</p> <!-- `{ name: 'DIO' }` is message vlaues -->
+     * ```
+     *
+     * `@intlify/core` (`@intlify/core-base`) `translate` case:
+     * ```js
+     * translate(context, 'foo.bar', ['dio']) // `['dio']` is message values
+     * ```
+     */
+    values: Record<string, unknown>;
 }
 
 export declare interface MessageContextOptions<T = string, N = {}> {
@@ -489,17 +633,22 @@ export declare interface MessageContextOptions<T = string, N = {}> {
     processor?: MessageProcessor<T>;
 }
 
+/**
+ * The Message Function.
+ *
+ * @param ctx - A {@link MessageContext}
+ *
+ * @return A resolved format message, that is string type basically.
+ *
+ * @VueI18nGeneral
+ */
 export declare type MessageFunction<T = string> = MessageFunctionCallable | MessageFunctionInternal<T>;
 
 export declare type MessageFunctionCallable = <T = string>(ctx: MessageContext<T>) => MessageFunctionReturn<T>;
 
-export declare type MessageFunctionInternal<T = string> = {
-    (ctx: MessageContext<T>): MessageFunctionReturn<T>;
-    key?: string;
-    locale?: string;
-    source?: string;
-};
+/* Excluded from this release type: MessageFunctionInternal */
 
+/** @VueI18nGeneral */
 export declare type MessageFunctionReturn<T = string> = T extends string ? MessageType<T> : MessageType<T>[];
 
 export declare type MessageFunctions<T = string> = Record<string, MessageFunction<T>>;