'use strict' ############################################################################################################ GUY_props = @ no_such_value = Symbol 'no_such_value' H = require './_helpers' builtins = require './_builtins' @_misfit = Symbol 'misfit' @_misfit2 = Symbol 'misfit2' { rpr, } = require './trm' ### see https://nodejs.org/dist/latest-v18.x/docs/api/util.html#utilinspectcustom ### node_inspect = Symbol.for 'nodejs.util.inspect.custom' #----------------------------------------------------------------------------------------------------------- H.types.declare 'guy_props_keys_cfg', tests: "@isa.object x": ( x ) -> @isa.object x "@isa_optional.cardinal x.depth": ( x ) -> @isa_optional.cardinal x.depth "@isa.boolean x.allow_any": ( x ) -> @isa.boolean x.allow_any "@isa.boolean x.symbols": ( x ) -> @isa.boolean x.symbols "@isa.boolean x.hidden": ( x ) -> @isa.boolean x.hidden "@isa.boolean x.depth_first": ( x ) -> @isa.boolean x.depth_first "@isa.boolean x.builtins": ( x ) -> @isa.boolean x.builtins "@isa.boolean x.builtins implies x.hidden": ( x ) -> return ( not x.builtins ) or ( x.hidden ) #........................................................................................................... H.types.defaults.guy_props_keys_cfg = allow_any: true symbols: false builtins: false hidden: false depth: null depth_first: false #----------------------------------------------------------------------------------------------------------- H.types.declare 'guy_props_crossmerge_cfg', tests: "@isa.guy_props_keys_cfg x": ( x ) -> @isa.guy_props_keys_cfg x "x.keys?": ( x ) -> x.keys? "x.values?": ( x ) -> x.values? "x.fallback can be anything": ( x ) -> true #........................................................................................................... ### TAINT code duplication ### H.types.defaults.guy_props_crossmerge_cfg = allow_any: true symbols: false builtins: false hidden: false depth: null depth_first: false keys: null values: null fallback: @_misfit #----------------------------------------------------------------------------------------------------------- H.types.declare 'guy_props_tree_cfg', tests: "@isa.guy_props_keys_cfg x": ( x ) -> @isa.guy_props_keys_cfg x "@isa_optional.function x.evaluate": ( x ) -> @isa_optional.function x.evaluate "@isa_optional.text x.sep": ( x ) -> @isa_optional.text x.sep #........................................................................................................... ### TAINT code duplication ### H.types.defaults.guy_props_tree_cfg = allow_any: true symbols: false builtins: false hidden: false depth: null depth_first: null evaluate: null sep: null #----------------------------------------------------------------------------------------------------------- H.types.declare 'guy_props_tree_verdict', ( x ) -> return true if @isa.boolean x return false unless @isa.text x return true #----------------------------------------------------------------------------------------------------------- H.types.declare 'guy_props_strict_owner', ( x ) -> x instanceof Strict_owner #----------------------------------------------------------------------------------------------------------- H.types.declare 'guy_props_strict_owner_cfg', tests: "@isa.object x": ( x ) -> @isa.object x "x.target?": ( x ) -> x.target? "@isa.boolean x.locked": ( x ) -> @isa.boolean x.locked "@isa.boolean x.seal": ( x ) -> @isa.boolean x.seal "@isa.boolean x.freeze": ( x ) -> @isa.boolean x.freeze "@isa.boolean x.oneshot": ( x ) -> @isa.boolean x.oneshot "@isa_optional.boolean x.reset": ( x ) -> @isa_optional.boolean x.reset # "reassignable object cannot be frozen": ( x ) -> # return false if x.oneshot and x.freeze # return true "x.reset is deprecated": ( x ) -> return true if x.reset? return true if x.reset is true throw new Error "^guy.props.Strict_owner@1^ `cfg.reset: false` is deprecated; use `cfg.seal: true` instead" #........................................................................................................... H.types.defaults.guy_props_strict_owner_cfg = target: null reset: true locked: true seal: false freeze: false oneshot: false #----------------------------------------------------------------------------------------------------------- @def = def = Object.defineProperty @hide = hide = ( object, name, value ) => Object.defineProperty object, name, enumerable: false writable: true configurable: true value: value #----------------------------------------------------------------------------------------------------------- @def_oneoff = def_oneoff = ( object, name, cfg, method ) => get = -> R = method.apply object delete cfg.get def object, name, configurable: ( cfg.configurable ? true ) enumerable: ( cfg.enumerable ? true ) value: R return R def object, name, { enumerable: true, configurable: true, get, } return null #----------------------------------------------------------------------------------------------------------- @_pick_with_fallback = ( d, fallback, keys... ) -> R = {} keys = keys.flat Infinity for key in keys R[ key ] = if ( value = d[ key ] ) is undefined then fallback else value return [ R, keys, ] #----------------------------------------------------------------------------------------------------------- @pick_with_fallback = ( d, fallback, keys... ) -> ( @_pick_with_fallback d, fallback, keys )[ 0 ] #----------------------------------------------------------------------------------------------------------- @pluck_with_fallback = ( d, fallback, keys... ) -> [ R, keys, ] = @_pick_with_fallback d, fallback, keys... delete d[ key ] for key in keys return R #----------------------------------------------------------------------------------------------------------- @nullify_undefined = ( d ) -> R = {} R[ k ] = ( v ? null ) for k, v of d return R #----------------------------------------------------------------------------------------------------------- @omit_nullish = ( d ) -> R = {} R[ k ] = v for k, v of d when v? return R #----------------------------------------------------------------------------------------------------------- @nonull_assign = ( first, others... ) -> return Object.assign {}, first, ( @omit_nullish other for other in others )... #----------------------------------------------------------------------------------------------------------- @crossmerge = ( cfg ) -> H.types.validate.guy_props_crossmerge_cfg ( cfg = { H.types.defaults.guy_props_crossmerge_cfg..., cfg..., } ) R = {} for key from @_walk_keys cfg.keys, cfg if ( value = @get cfg.values, key, @_misfit2 ) isnt @_misfit2 R[ key ] = value continue if cfg.fallback is @_misfit throw new Error "^guy.props.crossmerge@1^ missing key #{H.rpr key} in values" R[ key ] = cfg.fallback return R #----------------------------------------------------------------------------------------------------------- @resolve_property_chain = ( owner, property_chain ) -> R = owner R = R[ term ] for term in property_chain return R #----------------------------------------------------------------------------------------------------------- class @Strict_owner #--------------------------------------------------------------------------------------------------------- Strict_owner_cfg = Symbol 'Strict_owner_cfg' #--------------------------------------------------------------------------------------------------------- @_get_proxy_cfg: ( instance, cfg ) -> R = #..................................................................................................... ownKeys: ( target ) -> Reflect.ownKeys target #..................................................................................................... get: ( target, key ) -> return "#{instance.constructor.name}" if key is Symbol.toStringTag return target.constructor if key is 'constructor' return target.toString if key is 'toString' return target.call if key is 'call' return target.apply if key is 'apply' return target.then if key is 'then' return target[ Symbol.iterator ] if key is Symbol.iterator return target[ node_inspect ] if key is node_inspect ### NOTE necessitated by behavior of `node:util.inspect()`: ### return target[ 0 ] if key is '0' if ( value = GUY_props.get target, key, no_such_value ) is no_such_value return undefined unless cfg.locked throw new Error "^guy.props.Strict_owner@1^ #{instance.constructor.name} instance does not have property #{H.rpr key}" return value #..................................................................................................... set: ( target, key, value ) -> if GUY_props.has target, key throw new Error "^guy.props.Strict_owner@1^ #{instance.constructor.name} instance already has property #{H.rpr key}" return Reflect.set target, key, value #....................................................................................................... return R #--------------------------------------------------------------------------------------------------------- @get_locked: ( self ) -> return self[ Strict_owner_cfg ].locked #--------------------------------------------------------------------------------------------------------- @set_locked: ( self, flag ) -> H.types.validate.boolean flag self[ Strict_owner_cfg ].locked = flag return flag #--------------------------------------------------------------------------------------------------------- constructor: ( cfg ) -> ### thx to https://stackoverflow.com/a/40714458/7568091 ### cfg = { target: @, cfg..., } H.types.validate.guy_props_strict_owner_cfg cfg = { H.types.defaults.guy_props_strict_owner_cfg..., cfg..., } proxy_cfg = @constructor._get_proxy_cfg @, cfg delete proxy_cfg.set unless cfg.oneshot R = new Proxy cfg.target, proxy_cfg GUY_props.hide R, Strict_owner_cfg, cfg Object.freeze R if cfg.freeze Object.seal R if cfg.seal return R #--------------------------------------------------------------------------------------------------------- @create: ( cfg ) -> cfg = { target: {}, cfg..., } H.types.validate.guy_props_strict_owner_cfg cfg = { H.types.defaults.guy_props_strict_owner_cfg..., cfg..., } proxy_cfg = @_get_proxy_cfg cfg.target, cfg delete proxy_cfg.set unless cfg.oneshot R = new Proxy cfg.target, proxy_cfg GUY_props.hide R, Strict_owner_cfg, cfg ### TAINT consider to freeze, seal target instread of proxy ### Object.freeze R if cfg.freeze Object.seal R if cfg.seal return R #----------------------------------------------------------------------------------------------------------- Strict_owner = @Strict_owner #=========================================================================================================== # KEY TESTING, RETRIEVAL, CATALOGUING #----------------------------------------------------------------------------------------------------------- @has = ( target, key ) => ### safe version of `Reflect.has()` that never throws an error ### ### try to use `Reflect.has()` on given target; will fail for `null`, `undefined`, primitive values: ### try return Reflect.has target, key catch error then null ### try to retrieve prototype of target; will fail for `null`, `undefined`: ### try return false unless ( prototype = Object.getPrototypeOf target )? catch error then null ### give up if no prototye has been returned (may happen e.g. with `target = Object.create null`): ### return false unless prototype? ### apply `Reflect.has()` to prototype of target; this should be the definitive answer: ### return Reflect.has prototype, key #----------------------------------------------------------------------------------------------------------- get = ( target, key, fallback ) -> switch arity = arguments.length when 2 then fallback = @_misfit when 3 then null else throw new Error "^guy.props.get@1^ expected 2 or 3 arguments, got #{arity}" return target[ key ] if @has target, key return fallback unless fallback is @_misfit throw new Error "^guy.props.get@1^ no such property #{H.rpr key}" @get = get.bind @ ### avoiding fat-arrow function so we can use `arguments` ### #----------------------------------------------------------------------------------------------------------- @_get_keys_cfg = ( cfg ) -> has_hidden = ( cfg ? {} ).hidden? cfg = { H.types.defaults.guy_props_keys_cfg..., cfg..., } cfg.hidden = true if not has_hidden and cfg.builtins H.types.validate.guy_props_keys_cfg cfg return cfg #----------------------------------------------------------------------------------------------------------- @keys = ( owner, cfg ) => [ ( @_walk_keys owner, ( @_get_keys_cfg cfg ) )..., ] #----------------------------------------------------------------------------------------------------------- @has_any_keys = ( owner, cfg ) => return true for key from @_walk_keys owner, ( @_get_keys_cfg cfg ) return false #----------------------------------------------------------------------------------------------------------- @walk_keys = ( owner, cfg ) => return @_walk_keys owner, ( @_get_keys_cfg cfg ) #----------------------------------------------------------------------------------------------------------- @_walk_keys = ( owner, cfg ) -> seen = new Set() if cfg.depth_first cache = new Map() for { key, owner, } from @_walk_keyowners owner, cfg unless ( collector = cache.get owner )? cache.set owner, collector = [] collector.push key for owner in [ cache.keys()..., ].reverse() for key in cache.get owner continue if seen.has key seen.add key yield key else for { key, } from @_walk_keyowners owner, cfg continue if seen.has key seen.add key yield key return null #----------------------------------------------------------------------------------------------------------- @get_prototype_chain = ( x ) -> return [] unless x? R = [ x, ] loop break unless ( x = Object.getPrototypeOf x )? R.push x return R #----------------------------------------------------------------------------------------------------------- @_walk_keyowners = ( owner, cfg, current_depth = 0 ) -> return null if cfg.depth? and current_depth > cfg.depth return null if ( not cfg.builtins ) and builtins.has owner try for key in Reflect.ownKeys owner continue if ( not cfg.symbols ) and ( H.types.isa.symbol key ) d = Object.getOwnPropertyDescriptor owner, key continue if ( not cfg.hidden ) and ( not d.enumerable ) yield { key, owner, } catch error return null if cfg.allow_any and ( error.message is 'Reflect.ownKeys called on non-object' ) throw new Error "^guy.props._walk_keyowners@1^ Reflect.ownKeys called on non-object #{rpr owner}" #......................................................................................................... if ( proto_owner = Object.getPrototypeOf owner )? yield from @_walk_keyowners proto_owner, cfg, current_depth + 1 return null #----------------------------------------------------------------------------------------------------------- @xray = ( owner, base = {} ) => base[ k ] = owner[ k ] for k from @_walk_keys owner, { hidden: true, symbols: true, builtins: false, } return base #----------------------------------------------------------------------------------------------------------- ### thx to https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Object/getOwnPropertyDescriptors#creating_a_shallow_copy ### @_shallow_copy = ( d ) -> Object.create ( Object.getPrototypeOf d ), ( Object.getOwnPropertyDescriptors d ) #=========================================================================================================== # TREE #----------------------------------------------------------------------------------------------------------- @tree = ( owner, cfg ) -> [ ( @walk_tree owner, cfg )..., ] #----------------------------------------------------------------------------------------------------------- @walk_tree = ( owner, cfg ) -> H.types.validate.guy_props_tree_cfg ( cfg = { H.types.defaults.guy_props_tree_cfg..., cfg..., } ) unless cfg.sep? then return yield from @_walk_tree owner, cfg yield ( x.toString() for x in p ).join cfg.sep for p from @_walk_tree owner, cfg return null #----------------------------------------------------------------------------------------------------------- @_walk_tree = ( owner, cfg, seen ) -> seen ?= new Map() for { key, owner: subowner, } from @_walk_keyowners owner, cfg seen.set subowner, new Set() unless seen.has subowner continue if ( seen_keys = seen.get subowner ).has key seen_keys.add key try value = subowner[ key ] catch error continue if cfg.allow_any and ( /'caller', 'callee', and 'arguments' properties may not be accessed/.test error.message) verdict = if cfg.evaluate? then ( cfg.evaluate { owner: subowner, key, value, } ) else 'take,descend' H.types.validate.guy_props_tree_verdict verdict continue if verdict is false verdict = 'take,descend' if verdict is true yield [ key ] if /\btake\b/.test verdict continue unless /\bdescend\b/.test verdict for subkey from @_walk_tree value, cfg, seen yield [ key, subkey, ].flat() return null