@plasius/schema 1.1.1 → 1.2.0

package/dist/index.d.cts

@@ -241,7 +241,7 @@ type InferField<T> = T extends {
     shape: infer Shape extends SchemaShape;
 } ? InferFromShape<Shape> : unknown;
 type IsOptional<T> = T extends {
-    optional: true;
+    isRequired: false;
 } ? true : false;
 type InferFromShape<S extends SchemaShape> = {
     [K in keyof S]: IsOptional<S[K]> extends true ? InferField<S[K]> | undefined : InferField<S[K]>;
@@ -289,6 +289,21 @@ declare function getSchemaForType(type: string): Schema<any> | undefined;
  * Returns all schemas registered in the in-process global registry.
  */
 declare function getAllSchemas(): Schema<any>[];
+/**
+ * Renders a schema into a simplified descriptor for front-end consumption.
+ * Intended for documentation and admin tooling rather than validation.
+ */
+declare function renderSchemaDescription(schema: Schema<any>): {
+    title: string;
+    fields: Array<{
+        name: string;
+        type: FieldType;
+        optional: boolean;
+        description: string;
+        deprecated: boolean;
+        pii?: string;
+    }>;
+};
 
 declare function createComponentSchema<T extends SchemaShape>(shape: SchemaShape, name: string, version: string, tableName?: string, schemaValidator?: (entity: Infer<T>) => boolean): Schema<SchemaShape>;
 declare function registerComponentSchema(type: string, schema: Schema<SchemaShape>): void;
@@ -388,4 +403,225 @@ declare function validateName(value: unknown): boolean;
 declare function validateUserId(value: unknown): boolean;
 declare function validateUserIdArray(value: unknown): boolean;
 
-export { type DeepReadonly, FieldBuilder, type FieldDefinition, type FieldType, type FieldTypeMap, type Infer, type PIIEnforcement, type RefEntityId, type Schema, type SchemaOptions, type SchemaShape, type SchemaUpgradeFunction, type SchemaUpgradeResult, type SchemaUpgradeSpec, type SchemaUpgradeStep, type ValidateCompositionOptions, type ValidationResult, createComponentSchema, createSchema, field, getAllComponentSchemas, getAllSchemas, getComponentSchema, getSchemaForType, isoCountryCodes, isoCurrencyCodes, registerComponentSchema, validateCountryCode, validateCurrencyCode, validateDateTimeISO, validateEmail, validateName, validatePercentage, validatePhone, validateRichText, validateSafeText, validateSemVer, validateUUID, validateUrl, validateUserId, validateUserIdArray };
+/**
+ * ISO 639-1 language codes (two-letter).
+ * Tip: Keep this list as source of truth for supported languages in your app.
+ */
+declare enum IsoLanguageCode {
+    Afar = "aa",
+    Abkhazian = "ab",
+    Afrikaans = "af",
+    Akan = "ak",
+    Albanian = "sq",
+    Amharic = "am",
+    Arabic = "ar",
+    Aragonese = "an",
+    Armenian = "hy",
+    Assamese = "as",
+    Avaric = "av",
+    Aymara = "ay",
+    Azerbaijani = "az",
+    Bashkir = "ba",
+    Bambara = "bm",
+    Basque = "eu",
+    Belarusian = "be",
+    Bengali = "bn",
+    Bislama = "bi",
+    Bosnian = "bs",
+    Breton = "br",
+    Bulgarian = "bg",
+    Burmese = "my",
+    Catalan = "ca",
+    Chamorro = "ch",
+    Chechen = "ce",
+    Chinese = "zh",
+    ChurchSlavic = "cu",
+    Chuvash = "cv",
+    Cornish = "kw",
+    Corsican = "co",
+    Cree = "cr",
+    Croatian = "hr",
+    Czech = "cs",
+    Danish = "da",
+    Divehi = "dv",
+    Dutch = "nl",
+    Dzongkha = "dz",
+    English = "en",
+    Esperanto = "eo",
+    Estonian = "et",
+    Ewe = "ee",
+    Faroese = "fo",
+    Fijian = "fj",
+    Finnish = "fi",
+    French = "fr",
+    WesternFrisian = "fy",
+    Fulah = "ff",
+    Gaelic = "gd",
+    Galician = "gl",
+    Ganda = "lg",
+    Georgian = "ka",
+    German = "de",
+    Greek = "el",
+    Kalaallisut = "kl",
+    Guarani = "gn",
+    Gujarati = "gu",
+    Haitian = "ht",
+    Hausa = "ha",
+    Hebrew = "he",
+    Herero = "hz",
+    Hindi = "hi",
+    HiriMotu = "ho",
+    Hungarian = "hu",
+    Icelandic = "is",
+    Ido = "io",
+    Igbo = "ig",
+    Indonesian = "id",
+    Interlingua = "ia",
+    Interlingue = "ie",
+    Inuktitut = "iu",
+    Inupiaq = "ik",
+    Irish = "ga",
+    Italian = "it",
+    Japanese = "ja",
+    Javanese = "jv",
+    Kannada = "kn",
+    Kanuri = "kr",
+    Kashmiri = "ks",
+    Kazakh = "kk",
+    CentralKhmer = "km",
+    Kikuyu = "ki",
+    Kinyarwanda = "rw",
+    Kyrgyz = "ky",
+    Komi = "kv",
+    Kongo = "kg",
+    Korean = "ko",
+    Kuanyama = "kj",
+    Kurdish = "ku",
+    Lao = "lo",
+    Latin = "la",
+    Latvian = "lv",
+    Limburgan = "li",
+    Lingala = "ln",
+    Lithuanian = "lt",
+    LubaKatanga = "lu",
+    Luxembourgish = "lb",
+    Macedonian = "mk",
+    Malagasy = "mg",
+    Malay = "ms",
+    Malayalam = "ml",
+    Maltese = "mt",
+    Manx = "gv",
+    Maori = "mi",
+    Marathi = "mr",
+    Marshallese = "mh",
+    Mongolian = "mn",
+    Nauru = "na",
+    Navajo = "nv",
+    NorthNdebele = "nd",
+    SouthNdebele = "nr",
+    Ndonga = "ng",
+    Nepali = "ne",
+    Norwegian = "no",
+    NorwegianBokmal = "nb",
+    NorwegianNynorsk = "nn",
+    SichuanYi = "ii",
+    Occitan = "oc",
+    Ojibwa = "oj",
+    Oriya = "or",
+    Oromo = "om",
+    Ossetian = "os",
+    Pali = "pi",
+    Pashto = "ps",
+    Persian = "fa",
+    Polish = "pl",
+    Portuguese = "pt",
+    Punjabi = "pa",
+    Quechua = "qu",
+    Romansh = "rm",
+    Romanian = "ro",
+    Rundi = "rn",
+    Russian = "ru",
+    Samoan = "sm",
+    Sango = "sg",
+    Sanskrit = "sa",
+    Sardinian = "sc",
+    Serbian = "sr",
+    Shona = "sn",
+    Sindhi = "sd",
+    Sinhala = "si",
+    Slovak = "sk",
+    Slovenian = "sl",
+    Somali = "so",
+    SouthernSotho = "st",
+    Spanish = "es",
+    Sundanese = "su",
+    Swahili = "sw",
+    Swati = "ss",
+    Swedish = "sv",
+    Tagalog = "tl",
+    Tahitian = "ty",
+    Tajik = "tg",
+    Tamil = "ta",
+    Tatar = "tt",
+    Telugu = "te",
+    Thai = "th",
+    Tibetan = "bo",
+    Tigrinya = "ti",
+    Tonga = "to",
+    Tsonga = "ts",
+    Tswana = "tn",
+    Turkish = "tr",
+    Turkmen = "tk",
+    Twi = "tw",
+    Uighur = "ug",
+    Ukrainian = "uk",
+    Urdu = "ur",
+    Uzbek = "uz",
+    Venda = "ve",
+    Vietnamese = "vi",
+    Volapuk = "vo",
+    Walloon = "wa",
+    Welsh = "cy",
+    Wolof = "wo",
+    Xhosa = "xh",
+    Yiddish = "yi",
+    Yoruba = "yo",
+    Zhuang = "za",
+    Zulu = "zu"
+}
+/** Type guard: primary language must be one of the enum values. */
+declare function isIsoLanguageCode(value: unknown): value is IsoLanguageCode;
+/**
+ * Region validator per BCP 47:
+ * - ISO 3166-1 alpha-2: 2 uppercase letters (e.g., GB, US)
+ * - UN M.49 numeric: 3 digits (e.g., 419 for Latin America)
+ *
+ * NOTE: This validates *shape* not membership against the 3166 list.
+ * If you want hard membership, we can add a Set of all alpha-2 regions.
+ */
+declare function isRegionSubtag(value: string): boolean;
+/** Script subtag per ISO 15924: one capital + three lowercase (e.g., Latn, Cyrl, Hans). */
+declare function isScriptSubtag(value: string): boolean;
+/** Variant subtag per BCP 47: 5–8 alnum, or 4 starting with a digit. */
+declare function isVariantSubtag(value: string): boolean;
+/** Extension sequence: singleton (alnum except 'x') + one or more 2–8 alnum subtags. */
+declare function isExtensionSingleton(value: string): boolean;
+declare function isExtensionSubtag(value: string): boolean;
+/** Private-use subtag: 'x' then one or more 1–8 alnum subtags. */
+declare function isPrivateUseSingleton(value: string): boolean;
+declare function isPrivateUseSubtag(value: string): boolean;
+/**
+ * Validates:
+ *  - plain language: "en"
+ *  - language + region: "en-GB"
+ *  - language + script + region: "sr-Cyrl-RS"
+ *  - language + variants: "sl-rozaj-biske", "de-CH-1996"
+ *  - extensions: "en-GB-u-ca-gregory"
+ *  - private-use: "en-x-klingon" or just "x-piglatin"
+ *
+ * Returns true only if the primary language is in IsoLanguageCode
+ * and the rest of the tag conforms to BCP 47 structure.
+ */
+declare function validateLanguage(value: unknown): boolean;
+
+export { type DeepReadonly, FieldBuilder, type FieldDefinition, type FieldType, type FieldTypeMap, type Infer, IsoLanguageCode, type PIIEnforcement, type RefEntityId, type Schema, type SchemaOptions, type SchemaShape, type SchemaUpgradeFunction, type SchemaUpgradeResult, type SchemaUpgradeSpec, type SchemaUpgradeStep, type ValidateCompositionOptions, type ValidationResult, createComponentSchema, createSchema, field, getAllComponentSchemas, getAllSchemas, getComponentSchema, getSchemaForType, isExtensionSingleton, isExtensionSubtag, isIsoLanguageCode, isPrivateUseSingleton, isPrivateUseSubtag, isRegionSubtag, isScriptSubtag, isVariantSubtag, isoCountryCodes, isoCurrencyCodes, registerComponentSchema, renderSchemaDescription, validateCountryCode, validateCurrencyCode, validateDateTimeISO, validateEmail, validateLanguage, validateName, validatePercentage, validatePhone, validateRichText, validateSafeText, validateSemVer, validateUUID, validateUrl, validateUserId, validateUserIdArray };

package/dist/index.d.ts

@@ -241,7 +241,7 @@ type InferField<T> = T extends {
     shape: infer Shape extends SchemaShape;
 } ? InferFromShape<Shape> : unknown;
 type IsOptional<T> = T extends {
-    optional: true;
+    isRequired: false;
 } ? true : false;
 type InferFromShape<S extends SchemaShape> = {
     [K in keyof S]: IsOptional<S[K]> extends true ? InferField<S[K]> | undefined : InferField<S[K]>;
@@ -289,6 +289,21 @@ declare function getSchemaForType(type: string): Schema<any> | undefined;
  * Returns all schemas registered in the in-process global registry.
  */
 declare function getAllSchemas(): Schema<any>[];
+/**
+ * Renders a schema into a simplified descriptor for front-end consumption.
+ * Intended for documentation and admin tooling rather than validation.
+ */
+declare function renderSchemaDescription(schema: Schema<any>): {
+    title: string;
+    fields: Array<{
+        name: string;
+        type: FieldType;
+        optional: boolean;
+        description: string;
+        deprecated: boolean;
+        pii?: string;
+    }>;
+};
 
 declare function createComponentSchema<T extends SchemaShape>(shape: SchemaShape, name: string, version: string, tableName?: string, schemaValidator?: (entity: Infer<T>) => boolean): Schema<SchemaShape>;
 declare function registerComponentSchema(type: string, schema: Schema<SchemaShape>): void;
@@ -388,4 +403,225 @@ declare function validateName(value: unknown): boolean;
 declare function validateUserId(value: unknown): boolean;
 declare function validateUserIdArray(value: unknown): boolean;
 
-export { type DeepReadonly, FieldBuilder, type FieldDefinition, type FieldType, type FieldTypeMap, type Infer, type PIIEnforcement, type RefEntityId, type Schema, type SchemaOptions, type SchemaShape, type SchemaUpgradeFunction, type SchemaUpgradeResult, type SchemaUpgradeSpec, type SchemaUpgradeStep, type ValidateCompositionOptions, type ValidationResult, createComponentSchema, createSchema, field, getAllComponentSchemas, getAllSchemas, getComponentSchema, getSchemaForType, isoCountryCodes, isoCurrencyCodes, registerComponentSchema, validateCountryCode, validateCurrencyCode, validateDateTimeISO, validateEmail, validateName, validatePercentage, validatePhone, validateRichText, validateSafeText, validateSemVer, validateUUID, validateUrl, validateUserId, validateUserIdArray };
+/**
+ * ISO 639-1 language codes (two-letter).
+ * Tip: Keep this list as source of truth for supported languages in your app.
+ */
+declare enum IsoLanguageCode {
+    Afar = "aa",
+    Abkhazian = "ab",
+    Afrikaans = "af",
+    Akan = "ak",
+    Albanian = "sq",
+    Amharic = "am",
+    Arabic = "ar",
+    Aragonese = "an",
+    Armenian = "hy",
+    Assamese = "as",
+    Avaric = "av",
+    Aymara = "ay",
+    Azerbaijani = "az",
+    Bashkir = "ba",
+    Bambara = "bm",
+    Basque = "eu",
+    Belarusian = "be",
+    Bengali = "bn",
+    Bislama = "bi",
+    Bosnian = "bs",
+    Breton = "br",
+    Bulgarian = "bg",
+    Burmese = "my",
+    Catalan = "ca",
+    Chamorro = "ch",
+    Chechen = "ce",
+    Chinese = "zh",
+    ChurchSlavic = "cu",
+    Chuvash = "cv",
+    Cornish = "kw",
+    Corsican = "co",
+    Cree = "cr",
+    Croatian = "hr",
+    Czech = "cs",
+    Danish = "da",
+    Divehi = "dv",
+    Dutch = "nl",
+    Dzongkha = "dz",
+    English = "en",
+    Esperanto = "eo",
+    Estonian = "et",
+    Ewe = "ee",
+    Faroese = "fo",
+    Fijian = "fj",
+    Finnish = "fi",
+    French = "fr",
+    WesternFrisian = "fy",
+    Fulah = "ff",
+    Gaelic = "gd",
+    Galician = "gl",
+    Ganda = "lg",
+    Georgian = "ka",
+    German = "de",
+    Greek = "el",
+    Kalaallisut = "kl",
+    Guarani = "gn",
+    Gujarati = "gu",
+    Haitian = "ht",
+    Hausa = "ha",
+    Hebrew = "he",
+    Herero = "hz",
+    Hindi = "hi",
+    HiriMotu = "ho",
+    Hungarian = "hu",
+    Icelandic = "is",
+    Ido = "io",
+    Igbo = "ig",
+    Indonesian = "id",
+    Interlingua = "ia",
+    Interlingue = "ie",
+    Inuktitut = "iu",
+    Inupiaq = "ik",
+    Irish = "ga",
+    Italian = "it",
+    Japanese = "ja",
+    Javanese = "jv",
+    Kannada = "kn",
+    Kanuri = "kr",
+    Kashmiri = "ks",
+    Kazakh = "kk",
+    CentralKhmer = "km",
+    Kikuyu = "ki",
+    Kinyarwanda = "rw",
+    Kyrgyz = "ky",
+    Komi = "kv",
+    Kongo = "kg",
+    Korean = "ko",
+    Kuanyama = "kj",
+    Kurdish = "ku",
+    Lao = "lo",
+    Latin = "la",
+    Latvian = "lv",
+    Limburgan = "li",
+    Lingala = "ln",
+    Lithuanian = "lt",
+    LubaKatanga = "lu",
+    Luxembourgish = "lb",
+    Macedonian = "mk",
+    Malagasy = "mg",
+    Malay = "ms",
+    Malayalam = "ml",
+    Maltese = "mt",
+    Manx = "gv",
+    Maori = "mi",
+    Marathi = "mr",
+    Marshallese = "mh",
+    Mongolian = "mn",
+    Nauru = "na",
+    Navajo = "nv",
+    NorthNdebele = "nd",
+    SouthNdebele = "nr",
+    Ndonga = "ng",
+    Nepali = "ne",
+    Norwegian = "no",
+    NorwegianBokmal = "nb",
+    NorwegianNynorsk = "nn",
+    SichuanYi = "ii",
+    Occitan = "oc",
+    Ojibwa = "oj",
+    Oriya = "or",
+    Oromo = "om",
+    Ossetian = "os",
+    Pali = "pi",
+    Pashto = "ps",
+    Persian = "fa",
+    Polish = "pl",
+    Portuguese = "pt",
+    Punjabi = "pa",
+    Quechua = "qu",
+    Romansh = "rm",
+    Romanian = "ro",
+    Rundi = "rn",
+    Russian = "ru",
+    Samoan = "sm",
+    Sango = "sg",
+    Sanskrit = "sa",
+    Sardinian = "sc",
+    Serbian = "sr",
+    Shona = "sn",
+    Sindhi = "sd",
+    Sinhala = "si",
+    Slovak = "sk",
+    Slovenian = "sl",
+    Somali = "so",
+    SouthernSotho = "st",
+    Spanish = "es",
+    Sundanese = "su",
+    Swahili = "sw",
+    Swati = "ss",
+    Swedish = "sv",
+    Tagalog = "tl",
+    Tahitian = "ty",
+    Tajik = "tg",
+    Tamil = "ta",
+    Tatar = "tt",
+    Telugu = "te",
+    Thai = "th",
+    Tibetan = "bo",
+    Tigrinya = "ti",
+    Tonga = "to",
+    Tsonga = "ts",
+    Tswana = "tn",
+    Turkish = "tr",
+    Turkmen = "tk",
+    Twi = "tw",
+    Uighur = "ug",
+    Ukrainian = "uk",
+    Urdu = "ur",
+    Uzbek = "uz",
+    Venda = "ve",
+    Vietnamese = "vi",
+    Volapuk = "vo",
+    Walloon = "wa",
+    Welsh = "cy",
+    Wolof = "wo",
+    Xhosa = "xh",
+    Yiddish = "yi",
+    Yoruba = "yo",
+    Zhuang = "za",
+    Zulu = "zu"
+}
+/** Type guard: primary language must be one of the enum values. */
+declare function isIsoLanguageCode(value: unknown): value is IsoLanguageCode;
+/**
+ * Region validator per BCP 47:
+ * - ISO 3166-1 alpha-2: 2 uppercase letters (e.g., GB, US)
+ * - UN M.49 numeric: 3 digits (e.g., 419 for Latin America)
+ *
+ * NOTE: This validates *shape* not membership against the 3166 list.
+ * If you want hard membership, we can add a Set of all alpha-2 regions.
+ */
+declare function isRegionSubtag(value: string): boolean;
+/** Script subtag per ISO 15924: one capital + three lowercase (e.g., Latn, Cyrl, Hans). */
+declare function isScriptSubtag(value: string): boolean;
+/** Variant subtag per BCP 47: 5–8 alnum, or 4 starting with a digit. */
+declare function isVariantSubtag(value: string): boolean;
+/** Extension sequence: singleton (alnum except 'x') + one or more 2–8 alnum subtags. */
+declare function isExtensionSingleton(value: string): boolean;
+declare function isExtensionSubtag(value: string): boolean;
+/** Private-use subtag: 'x' then one or more 1–8 alnum subtags. */
+declare function isPrivateUseSingleton(value: string): boolean;
+declare function isPrivateUseSubtag(value: string): boolean;
+/**
+ * Validates:
+ *  - plain language: "en"
+ *  - language + region: "en-GB"
+ *  - language + script + region: "sr-Cyrl-RS"
+ *  - language + variants: "sl-rozaj-biske", "de-CH-1996"
+ *  - extensions: "en-GB-u-ca-gregory"
+ *  - private-use: "en-x-klingon" or just "x-piglatin"
+ *
+ * Returns true only if the primary language is in IsoLanguageCode
+ * and the rest of the tag conforms to BCP 47 structure.
+ */
+declare function validateLanguage(value: unknown): boolean;
+
+export { type DeepReadonly, FieldBuilder, type FieldDefinition, type FieldType, type FieldTypeMap, type Infer, IsoLanguageCode, type PIIEnforcement, type RefEntityId, type Schema, type SchemaOptions, type SchemaShape, type SchemaUpgradeFunction, type SchemaUpgradeResult, type SchemaUpgradeSpec, type SchemaUpgradeStep, type ValidateCompositionOptions, type ValidationResult, createComponentSchema, createSchema, field, getAllComponentSchemas, getAllSchemas, getComponentSchema, getSchemaForType, isExtensionSingleton, isExtensionSubtag, isIsoLanguageCode, isPrivateUseSingleton, isPrivateUseSubtag, isRegionSubtag, isScriptSubtag, isVariantSubtag, isoCountryCodes, isoCurrencyCodes, registerComponentSchema, renderSchemaDescription, validateCountryCode, validateCurrencyCode, validateDateTimeISO, validateEmail, validateLanguage, validateName, validatePercentage, validatePhone, validateRichText, validateSafeText, validateSemVer, validateUUID, validateUrl, validateUserId, validateUserIdArray };